Shipmail

https://shipmail.to/docs
Admin
Shipmail is a custom-domain email platform and developer API that provides mailboxes, calendars,...
Tokens:269,592
Snippets:2,208
Trust Score:6.5
Update:1 week ago
Show doc for...
Tokens:
Raw
### GET /v1/organization/access response example

Source: https://shipmail.to/docs/api/organization-access

Example response from the GET /v1/organization/access endpoint. Shows the organization's plan, access state, trial details, and mailbox limits. Use this to understand the shape of the response when building a client.

```json
{
  "object": "organization_access",
  "organization": { "id": "org_abc123", "name": "Acme" },
  "plan": "team",
  "has_access": true,
  "trial": { "active": true, "ends_at": "2026-10-19T09:00:00.000Z", "eligible": false },
  "mailboxes": { "limit": 3, "used": 1 },
  "newsletters_allowed": false
}
```

--------------------------------

### Clone and run the starter kit

Source: https://shipmail.to/docs/guides/email-for-ai-agents

Commands to copy the environment file, install dependencies, and start the local webhook server. Requires a scoped Shipmail key, mailbox ID, webhook signing secret, Anthropic key, and allowed senders in .env.local.

```bash
cp .env.example .env.local
bun install
bun --env-file .env.local run dev
```

--------------------------------

### Install the shipmail SDK

Source: https://shipmail.to/docs/guides/send-email-from-express

Run this command to install the shipmail TypeScript SDK.

```bash
npm install shipmail
```

--------------------------------

### Install the Shipmail Python SDK

Source: https://shipmail.to/docs/guides/send-email-from-django

Install the Shipmail Python SDK using pip.

```bash
pip install shipmail
```

--------------------------------

### Install shipmail-cli with npx or npm

Source: https://shipmail.to/docs/cli

Install the CLI globally with npm or run it directly with npx. The --help flag displays usage information.

```bash
npx -y shipmail-cli --help

# Or install globally
npm install -g shipmail-cli
shipmail --help
```

--------------------------------

### Install shipmail with uv

Source: https://shipmail.to/docs/sdks/python

Install the official shipmail package in Python 3.10+ environment.

```shell
uv add shipmail
```

--------------------------------

### Upload an export file - response example

Source: https://shipmail.to/docs/api/mailboxes

Example response from POST /mailboxes/{id}/imports/files. Shows the file_id, part size, completed parts, presigned upload URLs, and expiration. Use the part_size_bytes to split the file and PUT each part to its upload_url.

```json
{
  "object": "import_upload",
  "file_id": "impf_abc123",
  "part_size_bytes": 33554432,
  "completed_parts": [],
  "parts": [
    { "part_number": 1, "upload_url": "https://storage.example/...?partNumber=1" }
  ],
  "expires_in_seconds": 518400
}
```

--------------------------------

### Use with newsletters - JavaScript example

Source: https://shipmail.to/docs/api/newsletter-sender-identities

JavaScript example showing how to list sender identities, find the default verified identity, and create a newsletter with that sender. Throws an error if no verified identity exists.

```javascript
const identities = await shipmail.newsletters.senderIdentities.list({
  limit: 25,
});

const sender = identities.data.find(
  (identity) => identity.is_default && identity.domain_status === "verified",
);
if (!sender) {
  throw new Error("No verified newsletter sender identity.");
}

const newsletter = await shipmail.newsletters.create({
  audience_id: "aud_abc123",
  sender_identity_id: sender.id,
  name: "July changelog",
  subject: "What shipped in July",
  body_html: "<h1>July updates</h1><p>...</p>",
});
```

--------------------------------

### Start an import with curl

Source: https://shipmail.to/docs/api/mailboxes

Starts a background import from an IMAP provider (Gmail) into a mailbox. Requires the mailboxes:write scope and a write-tier API key. The source can be an IMAP connection or staged files. Returns 201 on success or 409 if an import is already running.

```bash
curl -X POST https://shipmail.to/api/v1/mailboxes/f47ac10b-58cc-4372-a567-0e02b2c3d479/imports \
  -H "Authorization: Bearer sm_live_..." \
  -H "Content-Type: application/json" \
  -d '{
    "source": {
      "type": "imap",
      "provider": "gmail",
      "email": "you@gmail.com",
      "password": "your-app-password"
    },
    "options": { "range": "12m" }
  }'
```

--------------------------------

### Shipmail Quick start: send messages and manage mailboxes

Source: https://shipmail.to/docs/sdks/python

Quick start showing Shipmail client creation and sending a message, then listing by client_reference, suspending/resuming mailboxes, managing forwarding, app passwords, rules, and exports. Uses a live API key and prints several response fields.

```python
from shipmail import Shipmail

client = Shipmail("sm_live_...")

message = client.messages.send({
    "from": "hello@yourdomain.com",
    "to": ["recipient@example.com"],
    "subject": "Hello from Shipmail",
    "text": "It works.",
    "client_reference": "crm-123",
    "metadata": {"campaign": "onboarding"},
    "source_rfc_message_id": "<crm-123@yourdomain.com>",
})

same_message = client.messages.list({"client_reference": "crm-123"})
client.mailboxes.suspend("mbx_123")
client.mailboxes.resume("mbx_123")
forwarding = client.mailboxes.create_forwarding("mbx_123", {
    "destination": "owner@example.net",
})
forwarding_list = client.mailboxes.list_forwarding("mbx_123")
app_password = client.mailboxes.create_app_password("mbx_123", {
    "name": "Desktop mail",
    "expires_at": "2026-10-01T00:00:00Z",
})
app_passwords = client.mailboxes.list_app_passwords("mbx_123")
client.mailboxes.revoke_app_password("mbx_123", app_password["id"])
rules = client.mailboxes.get_rules("mbx_123")
client.mailboxes.update_rules("mbx_123", {"rules": rules["rules"]})
mailbox_export = client.mailboxes.create_export("mbx_123")
export_status = client.mailboxes.get_export("mbx_123", mailbox_export["id"])
print(message["id"], same_message["data"][0]["id"], forwarding["status"], len(forwarding_list["data"]))
```

--------------------------------

### GET /api/v1/domains (API key)

Source: https://shipmail.to/docs/api/authentication

Example request to the domains endpoint using an API key as a Bearer token.

```APIDOC
## GET /api/v1/domains

### Description
Retrieves domains using an API key for authentication.

### Method
GET

### Endpoint
/api/v1/domains

### Authentication
Bearer token (API key)

### Request Example
```
curl https://shipmail.to/api/v1/domains \
  -H "Authorization: Bearer sm_live_..."
```

### Response
No response schema provided in the source.
```

--------------------------------

### GET /api/v1/domains (OAuth access token)

Source: https://shipmail.to/docs/api/authentication

Example request to the domains endpoint using an OAuth access token and an organization header.

```APIDOC
## GET /api/v1/domains

### Description
Retrieves domains using an OAuth access token for authentication. The organization must be specified with the X-Shipmail-Organization header when multiple organizations are approved.

### Method
GET

### Endpoint
/api/v1/domains

### Authentication
Bearer token (OAuth access token)

### Headers
- **X-Shipmail-Organization** (string) - Required when multiple organizations are approved - The organization ID the request acts on.

### Request Example
```
curl https://shipmail.to/api/v1/domains \
  -H "Authorization: Bearer <access_token>" \
  -H "X-Shipmail-Organization: <organization_id>"
```

### Response
No response schema provided in the source.
```

--------------------------------

### List suppressions response

Source: https://shipmail.to/docs/api/suppressions

Example response from GET /v1/suppressions. Requires the suppressions:read scope and supports pagination with cursor and limit parameters.

```json
{
  "data": [
    {
      "object": "suppression",
      "email_address": "user@example.com",
      "reason": "hard_bounce",
      "created_at": "2026-05-13T10:00:00.000Z"
    }
  ],
  "pagination": {
    "next_cursor": null,
    "has_more": false,
    "limit": 25
  }
}
```

--------------------------------

### Quick start: send email and manage mailboxes

Source: https://shipmail.to/docs/sdks/typescript

Initializes the Shipmail client with an API key, sends an email, and demonstrates listing messages, suspending/resuming mailboxes, creating and listing forwarding rules, managing app passwords, updating rules, and creating exports. Requires the SHIPMAIL_API_KEY environment variable.

```javascript
import Shipmail from "shipmail";

const shipmail = new Shipmail(process.env.SHIPMAIL_API_KEY);

// Send an email
const message = await shipmail.messages.send({
  from: "hello@yourdomain.com",
  to: ["recipient@example.com"],
  subject: "Hello from Shipmail",
  text: "It works.",
  client_reference: "crm-123",
  metadata: { campaign: "onboarding" },
  source_rfc_message_id: "<crm-123@yourdomain.com>",
});

const sameMessage = await shipmail.messages.list({ client_reference: "crm-123" });
await shipmail.mailboxes.suspend("mbx_123");
await shipmail.mailboxes.resume("mbx_123");
const forwarding = await shipmail.mailboxes.createForwarding("mbx_123", {
  destination: "owner@example.net",
});
const forwardingList = await shipmail.mailboxes.listForwarding("mbx_123");
const appPassword = await shipmail.mailboxes.createAppPassword("mbx_123", {
  name: "Desktop mail",
  expires_at: "2026-10-01T00:00:00Z",
});
const appPasswords = await shipmail.mailboxes.listAppPasswords("mbx_123");
await shipmail.mailboxes.revokeAppPassword("mbx_123", appPassword.id);
const rules = await shipmail.mailboxes.getRules("mbx_123");
await shipmail.mailboxes.updateRules("mbx_123", {
  rules: rules.rules,
});
const mailboxExport = await shipmail.mailboxes.createExport("mbx_123");
const exportStatus = await shipmail.mailboxes.getExport("mbx_123", mailboxExport.id);
console.log(message.id, sameMessage.data[0]?.id, forwarding.status, forwardingList.data.length);
```

--------------------------------

### shipmail api: GET and POST requests with JSON data and file output

Source: https://shipmail.to/docs/cli

Use `shipmail api` for endpoints that need full JSON bodies, binary downloads, or custom headers. Paths are relative to the API base URL. The example shows a GET request, a POST request with a JSON body, and a GET request with query parameters and file output.

```bash
shipmail api GET /domains

shipmail api POST /mailboxes/f47ac10b-58cc-4372-a567-0e02b2c3d479/folders \
  --data '{"name":"Finance"}'

shipmail api GET "/mailboxes/f47ac10b-58cc-4372-a567-0e02b2c3d479/inbox/attachments?blob_id=abc&name=invoice.pdf" \
  --output invoice.pdf
```

--------------------------------

### List sender identities - JSON response

Source: https://shipmail.to/docs/api/newsletter-sender-identities

Example JSON response from the GET /v1/newsletter-sender-identities endpoint, showing a single sender identity object with fields like from_name, business_name, domain_status, and pagination details.

```json
{
  "data": [
    {
      "object": "newsletter_sender_identity",
      "id": "nwsid_abc123",
      "newsletter_domain_id": "nwsdom_abc123",
      "from_name": "Acme Product Team",
      "from_address": "updates@news.example.com",
      "business_name": "Acme Holdings Ltd.",
      "postal_address": "1 Market Street, London",
      "footer_text": "Product news for Acme customers.",
      "domain_status": "verified",
      "is_default": true,
      "created_at": "2026-07-29T12:00:00.000Z",
      "updated_at": "2026-07-29T12:00:00.000Z"
    }
  ],
  "pagination": {
    "next_cursor": null,
    "has_more": false,
    "limit": 25
  }
}
```

--------------------------------

### Create webhook and add domain in TypeScript

Source: https://shipmail.to/docs/api/quick-start

Automates domain setup by subscribing to the domain.verified event instead of polling. Creates a webhook, adds a domain, and waits for the event. Save webhook.secret for signature verification.

```typescript
// 1. Create a webhook for domain events
const webhook = await shipmail.webhooks.create({
  url: "https://yourapp.com/api/webhooks/shipmail",
  events: ["domain.verified", "domain.verification_failed"],
});
// Save webhook.secret for signature verification

// 2. Add the domain
const domain = await shipmail.domains.create({ name: "example.com" });

// 3. Add DNS records at your provider, then wait for the webhook
// shipmail sends a domain.verified event when all records pass
```

--------------------------------

### Calendar availability response object

Source: https://shipmail.to/docs/api/calendar

Example response from GET /v1/calendar/availability. Requires mailbox, from, and to. Optional parameters include duration (default 30 minutes), interval, timezone, days, window_start, window_end, buffer, and minimum_notice.

```json
{
  "object": "calendar_availability",
  "mailbox": "hello@yourdomain.com",
  "from": "2026-08-03T00:00:00.000Z",
  "to": "2026-08-04T00:00:00.000Z",
  "duration_minutes": 30,
  "timezone": "America/New_York",
  "slots": [
    { "start": "2026-08-03T13:00:00.000Z", "end": "2026-08-03T13:30:00.000Z" }
  ]
}
```

--------------------------------

### Run production smoke test with bun run qa

Source: https://shipmail.to/docs/mcp/security

Runs the repository QA command, which installs the published npm package in a temporary directory and connects over MCP stdio to verify startup, tool registration, and status access without changing account state.

```bash
bun run qa
```

--------------------------------

### Install shipmail-mcp stdio server configuration

Source: https://shipmail.to/docs/mcp

Configuration for any MCP host that supports stdio servers. Serves both the current 2026-07-28 protocol and the earlier 2025-11-25. Create API keys from the shipmail dashboard; see API authentication for setup details.

```json
{
  "mcpServers": {
    "shipmail": {
      "command": "npx",
      "args": ["-y", "shipmail-mcp"],
      "env": {
        "SHIPMAIL_API_KEY": "sm_live_..."
      }
    }
  }
}
```

--------------------------------

### Create newsletter from changelog and manage lifecycle

Source: https://shipmail.to/docs/api/newsletters

JavaScript example showing how to create a newsletter from a changelog, then preview, send a test, preflight, and schedule it. Uses the Shipmail client.

```javascript
const newsletter = await shipmail.newsletters.createFromChangelog({
  audience_id: "aud_abc123",
  sender_identity_id: "nwsid_abc123",
  name: "July changelog",
  subject: "What shipped in July",
  preview_text: "A quick product update",
  tone: "friendly",
  entries: [
    {
      title: "Reusable media library",
      body: "Search recent newsletter images and videos, then insert them again.",
      media: [{ kind: "image", url: "https://cdn.example.com/media-picker.png", alt: "Media picker" }],
    },
  ],
  final_cta: { label: "Read the changelog", url: "https://example.com/changelog" },
});

await shipmail.newsletters.preview(newsletter.id);

await shipmail.newsletters.sendTest(newsletter.id, {
  recipient_email: "owner@example.com",
});

await shipmail.newsletters.preflight(newsletter.id);

await shipmail.newsletters.schedule(newsletter.id, {
  scheduled_at: "2026-08-01T09:00:00.000Z",
});
```

--------------------------------

### Deploy Edge Function

Source: https://shipmail.to/docs/guides/send-email-from-supabase

Deploys the `send-welcome-email` function to Supabase.

```bash
supabase functions deploy send-welcome-email
```

--------------------------------

### Create and manage automations

Source: https://shipmail.to/docs/cli

Creates an automation from a definition file, then updates its status and runs it. The definition flag accepts inline JSON or an @file. Creation and updates accept --idempotency-key.

```bash
shipmail automations create   --name "Daily brief"   --definition @automation.json

shipmail automations update aaut_123 --status paused
shipmail automations run aaut_123
```

--------------------------------

### Existing SPF record example

Source: https://shipmail.to/docs/domains

Example of an existing SPF record that needs to be merged with Shipmail's SPF record.

```text
v=spf1 include:_spf.google.com -all
```

--------------------------------

### Configure Shipmail client with options

Source: https://shipmail.to/docs/sdks/typescript

Shows how to instantiate the Shipmail client with an options object for full control. The baseUrl, maxRetries, timeout, and defaultHeaders are optional with defaults shown in the table. The apiKey is required and should be an sm_live_... key.

```typescript
const shipmail = new Shipmail({
  apiKey: process.env.SHIPMAIL_API_KEY,
  baseUrl: "https://shipmail.to/api/v1",  // default
  maxRetries: 2,                           // default
  timeout: 30_000,                         // ms, default
  defaultHeaders: { "X-Custom": "value" },
});
```

--------------------------------

### calendar.event_starting

Source: https://shipmail.to/docs/api/webhooks

Fires 15 minutes before an event starts, up to 6 minutes early and at most 2 minutes late. Cancelled and all-day events are excluded. A moved event fires again for its new start.

```APIDOC
## calendar.event_starting

### Description
Fires 15 minutes before an event starts, up to 6 minutes early and at most 2 minutes late. Cancelled and all-day events are excluded. A moved event fires again for its new start.

### Event Name
`calendar.event_starting`

### Trigger
- Fires 15 minutes before an event starts.
- Timing window: up to 6 minutes early and at most 2 minutes late.
- Cancelled and all-day events are excluded.
- A moved event fires again for its new start.

### Payload
- `event_id` (string) - Derived from what triggered the event, ensuring each event fires only once.
- `event_title` (string) - The title of the event, written by another person; treat as data.

### Notes
- Fires once.
- Does not carry a message body, event description, or booking note.
```

--------------------------------

### Install Shipmail SDK with bun

Source: https://shipmail.to/docs/guides/send-email-from-nextjs

Adds the Shipmail SDK to your project using the bun package manager.

```bash
bun add shipmail
```

--------------------------------

### shipmail.status

Source: https://shipmail.to/docs/sdks/typescript

Get the API status.

```APIDOC
## shipmail.status

### Description
Get the API status.

### Methods
- get
```

--------------------------------

### Search and register a domain with TypeScript SDK

Source: https://shipmail.to/docs/api/quick-start

Optional alternative to steps 3 and 4: search for available domains and register one. Registration charges your saved payment method and configures DNS automatically.

```typescript
// Search for available domains
const { results } = await shipmail.domains.search({ keyword: "mycompany" });
const available = results.filter((r) => r.available);

// Register a domain (charges your saved payment method)
const domain = await shipmail.domains.register({
  name: "mycompany.com",
  contact: {
    first_name: "Jane",
    last_name: "Doe",
    address1: "123 Main St",
    city: "San Francisco",
    state: "CA",
    zip: "94105",
    country: "US",
    phone: "+14155551234",
    email: "jane@example.com",
  },
});
// Domain is registered, DNS is configured automatically
```
Tokens:
Raw