@smbcloud / cli
Code Commits Issues Pulls Cloud Agent CI/CD
main
claude/smbcloud-github-app-k9641p development feature/apps feature/build-release feature/ci-docs feature/ci-ruby-gems feature/cicd feature/completion feature/dist-nuget feature/fix-ci-sdk-pypi-rubygem feature/fix-clippy-on-stable-channel feature/fix-deployment-script feature/github-email feature/gresiq-v1 feature/project-new-structure feature/rsync-deploy feature/ruby-runner feature/sdk-npm feature/sdk-workflows feature/smbcloud-cli-release-npm feature/smbcloud-deploy feature/wasm main release/v0.7.4
mdx 89 lines 3.12 KB
Raw
1 ---
2 title: Mail
3 description: smbCloud Mail is the transactional email service. Send from your own verified domain over the API, read delivery status for every message, and route inbound mail where it needs to go.
4 ---
5
6 # Mail
7
8 Mail is the email service for your product. Send transactional email from your own
9 domain over the API, then read what happened to each message. The same domain also
10 routes inbound mail, so receipts go out and replies come back through one place.
11
12 ## Send transactional email
13
14 Mint an API key for your Mail app in the console. Keys look like `smb_mail_…`, and
15 sending is scoped to the domain that Mail app has verified.
16
17 ```sh
18 curl -X POST https://api.smbcloud.xyz/v1/email/messages \
19 -H "Authorization: Bearer smb_mail_your_key" \
20 -H "Content-Type: application/json" \
21 -d '{
22 "from": "billing@example.com",
23 "to": ["customer@acme.com"],
24 "subject": "Your receipt",
25 "html": "<h1>Thanks!</h1>",
26 "idempotency_key": "receipt-2026-0001"
27 }'
28 ```
29
30 At least one of `html` or `text` is required, and `from` must sit on the verified
31 domain. Messages also take `cc`, `bcc`, `reply_to`, base64 attachments, custom
32 headers, and tags.
33
34 Reuse an `idempotency_key` and you get the original message back instead of a second
35 send, which is what you want when a retry fires after a timeout.
36
37 From Rust, use [`smbcloud-email-sdk`](https://crates.io/crates/smbcloud-email-sdk):
38
39 ```rust
40 let message = SendEmail::new("billing@example.com", ["customer@acme.com"])
41 .subject("Your receipt")
42 .html("<h1>Thanks!</h1>")
43 .idempotency_key("receipt-2026-0001");
44
45 let sent = client.send(&message).await?;
46 ```
47
48 ## Track delivery
49
50 Every message carries a status: queued, sent, delivered, bounced, complained, or
51 failed. Fetch one message for its full event timeline, or list recent messages
52 filtered by status when you want to see what bounced.
53
54 ```sh
55 curl "https://api.smbcloud.xyz/v1/email/messages?status=bounced&limit=20" \
56 -H "Authorization: Bearer smb_mail_your_read_key"
57 ```
58
59 Reading messages needs a read-scope key. Sending keys cannot read.
60
61 ## Receive and route
62
63 A Mail app maps to one domain and holds many inbox routes. Each route forwards
64 inbound mail where it needs to go, and stores the message so you keep the history.
65
66 - Run one Mail app per domain
67 - Set up many inbox routes on a Mail app
68 - Forward inbound mail where it needs to go
69 - Store inbound message history
70
71 A project can have many Mail apps. The domain setup, meaning DNS, bucket, prefix,
72 and shared routing, lives on the Mail app's setup page, out of the way of everyday
73 inbox work.
74
75 ## Getting started
76
77 1. Create a Mail app for your domain.
78 2. Complete the domain setup (DNS and routing) on the Mail app's setup page.
79 3. Mint an API key to send, or add inbox routes to receive.
80
81 Mail handles transactional email and domain routing. It is not a hosted mailbox
82 suite: for business mailboxes you read in an app, see
83 [smbCloud Mail for business](https://smbcloudmail.com).
84
85 ## From the CLI or an AI agent
86
87 `smb mail` manages Mail apps and inbox routes from the terminal, and the same
88 operations are available to Claude, Cursor, and other agents through the
89 [MCP server](/developer/cli/mcp).