diff --git a/docs/getting-started/account.md b/docs/getting-started/account.md index a5deadb..7d44826 100644 --- a/docs/getting-started/account.md +++ b/docs/getting-started/account.md @@ -13,3 +13,8 @@ You can create an account using your Github account by clicking the "Continue wi Alternatively you can create an account using your email address and password by clicking "Sign Up". If chosen to create an account using your email address, we will ask for your first name, last name and email. You'll then be asked to enter a password. Finally we will ask you to verify the email address you've provided. You should receive an email with a 6 digit code. + +## Reference Documentation + +For more details about accounts and the data model: +* [Data Model](/docs/reference/data-model) - Complete overview of accounts, API tokens, audiences, and alerts diff --git a/docs/getting-started/adding-funds.md b/docs/getting-started/adding-funds.md index cc069c8..91930ea 100644 --- a/docs/getting-started/adding-funds.md +++ b/docs/getting-started/adding-funds.md @@ -51,4 +51,10 @@ View all account activity on the [Billing](https://console.notifox.com/?view=bil ## Next Steps -Now that you have funds, you're ready to [send your first alert](/docs/getting-started/alert)! \ No newline at end of file +Now that you have funds, you're ready to [send your first alert](/docs/getting-started/alert)! + +## Reference Documentation + +For more details about pricing and costs: +* [SMS Parts Reference](/docs/reference/parts) - Understanding SMS parts, encoding, and cost calculation +* [Data Model](/docs/reference/data-model) - Overview of accounts, balances, and billing \ No newline at end of file diff --git a/docs/getting-started/alert.md b/docs/getting-started/alert.md index dcae795..6d29f27 100644 --- a/docs/getting-started/alert.md +++ b/docs/getting-started/alert.md @@ -8,23 +8,32 @@ Now that you have an account, API token, and verified audience, you're ready to ## What Are Alerts? -Alerts are messages you send through the Notifox API. Notifox supports two channels: +An **alert** is a message you send through the Notifox API to a specific audience via a chosen channel. -* **SMS** - Text messages sent to phone numbers -* **Email** - Emails sent to email addresses +**Alert Structure:** +- **audience** (required): The audience identifier/slug (e.g., `"joe"`, `"oncall"`) - see [Creating an Audience](./audience.md) +- **alert** (required): The message content (string) +- **channel** (required): Either `"sms"` or `"email"` - the delivery method + +Notifox supports two channels: + +* **SMS** - Text messages sent to verified phone numbers +* **Email** - Emails sent to verified email addresses They're perfect for: * Notifying yourself or your team about server issues * Sending critical system alerts * Getting notified about important events in your application +For a complete overview of how alerts, audiences, channels, and other objects relate, see the [Data Model](/docs/reference/data-model) reference. + ## Choosing a Channel When sending an alert, you can specify the `channel` parameter: | Channel | Cost | Max Length | Best For | |---------|------|------------|----------| -| `sms` | $0.025/part | ~765 chars (5 parts) | Urgent, time-sensitive alerts | +| `sms` | $0.025/part | 765 chars (5 parts) | Urgent, time-sensitive alerts | | `email` | $0.001/email | 50,000 chars | Detailed alerts, logs, reports | **Note:** The channel you choose must be configured for the audience. For example, if you want to send an email, the audience must have a verified email address. diff --git a/docs/getting-started/api-token.md b/docs/getting-started/api-token.md index a4719d1..dd1decb 100644 --- a/docs/getting-started/api-token.md +++ b/docs/getting-started/api-token.md @@ -4,7 +4,19 @@ sidebar_position: 2 # Create an API token -An API token (or sometimes referred to as API key) is used to authenticate with the Notifox API. +An **API token** (also called API key) is a secret string used to authenticate all requests to the Notifox API. + +**Type:** String (secret credential) + +**Format:** Alphanumeric string, typically 40+ characters + +**Usage:** Include in the `Authorization: Bearer ` header for all API requests + +**Important:** +- API tokens are secrets: treat them like passwords +- Each token is shown only once when created +- You can create up to 10 API tokens per account +- Tokens don't expire unless you delete them ## Creating an API token @@ -57,4 +69,10 @@ Keep in mind that once you delete an API token, it can no longer be used. Any re * **Rotate tokens regularly**: Periodically delete old tokens and create new ones, especially if you suspect a token may have been compromised. * **Use different tokens for different environments**: Create separate tokens for production, staging, and development to better track usage and limit blast radius if one is compromised. * **Don't share tokens**: API tokens grant full access to send alerts from your account. Only share tokens with trusted team members who need API access. -* **Delete unused tokens**: Remove tokens that are no longer in use to reduce your attack surface. \ No newline at end of file +* **Delete unused tokens**: Remove tokens that are no longer in use to reduce your attack surface. + +## Reference Documentation + +For more details about API tokens and authentication: +* [Data Model](/docs/reference/data-model) - Overview of API tokens and other core objects +* [Alerts API Reference](/docs/reference/alerts-api) - API authentication and error handling \ No newline at end of file diff --git a/docs/getting-started/audience.md b/docs/getting-started/audience.md index 6e5ba50..a84b30f 100644 --- a/docs/getting-started/audience.md +++ b/docs/getting-started/audience.md @@ -4,12 +4,19 @@ sidebar_position: 3 # Create an Audience -Audiences are how you tell Notifox who should receive your alerts. Think of an audience as a named contact—like "joe", "oncall" or "dev-team" that you can reference when sending alerts. +An **audience** is a named identifier (slug) that maps to verified contact methods. Think of it as a label you create (like `"joe"`, `"oncall"`, or `"dev-team"`) that you reference when sending alerts through the API. + +**Important:** An audience is: +- A **slug/identifier** (string) that you choose +- **Not** a user ID, email address, or phone number +- A way to reference verified contact methods in your API calls Each audience can have: -* A **phone number** for SMS alerts -* An **email address** for email alerts -* Or both! +* **At most one** verified phone number for SMS alerts (or none) +* **At most one** verified email address for email alerts (or none) +* Or both (one phone + one email) + +**Example:** If you create an audience named `"joe"` with a verified phone number and email, you can send alerts to `"joe"` via SMS or email by specifying the channel in your API request. An audience can also have just a phone number, just an email address, or both. Let's create your first audience together. @@ -19,7 +26,7 @@ Head over to the [Audiences](https://console.notifox.com/?view=audiences) page a ![audience modal](./images/audience-1.png) -You'll see a simple form asking for an audience name. Choose something descriptive that you'll remember—like `oncall`, `dev-team`, or `support`. The name can include letters, numbers, hyphens, and underscores, but no spaces. +You'll see a simple form asking for an audience name. Choose something descriptive that you'll remember, like `oncall`, `dev-team`, or `support`. The name can include letters, numbers, hyphens, and underscores, but no spaces. Click **Create Audience** when you're ready. You'll automatically be taken to the detailed view for your new audience. @@ -33,7 +40,7 @@ In the detailed view, you'll see a **Phone Number** section with an **Add** butt ![add phone modal](./images/audience-2.png) -Enter your US phone number (it should start with `+1`). The form will help you format it correctly. You'll also see a brief message about SMS alerts—this is required for compliance. +Enter your US phone number (it should start with `+1`). The form will help you format it correctly. You'll also see a brief message about SMS alerts: this is required for compliance. Click **Add Phone Number**. Notifox will automatically send a 6-digit verification code to that number via SMS. @@ -63,7 +70,7 @@ Your audience is now ready to use. You'll see it listed on the [Audiences](https ![audiences list](./images/audience-4.png) -You can click the edit icon (pencil) next to any audience to manage it—add or remove phone numbers and email addresses, or delete the audience entirely. +You can click the edit icon (pencil) next to any audience to manage it: add or remove phone numbers and email addresses, or delete the audience entirely. ## Which channel to use? @@ -74,4 +81,10 @@ You can click the edit icon (pencil) next to any audience to manage it—add or You can configure both channels on the same audience and choose which one to use when sending each alert. -**What's next?** Now that you have an audience set up, you're ready to [add some funds](./adding-funds.md) and send your first alert! \ No newline at end of file +**What's next?** Now that you have an audience set up, you're ready to [add some funds](./adding-funds.md) and send your first alert! + +## Reference Documentation + +For more details about audiences and the data model: +* [Data Model](/docs/reference/data-model) - Complete overview of audiences, alerts, channels, and how they relate +* [Alerts API Reference](/docs/reference/alerts-api) - Full API documentation for sending alerts \ No newline at end of file diff --git a/docs/intro.md b/docs/intro.md index b3d02cd..02c9e9a 100644 --- a/docs/intro.md +++ b/docs/intro.md @@ -20,7 +20,7 @@ But most notification platforms are built for marketing teams, not developers: * **Single-channel limitations**: Many services only support one channel (SMS or email), forcing you to use multiple providers for different use cases. -* **Expensive and complex**: Traditional SMS providers require carrier verification, campaign registration, and number leasing—costing $18-24 before you send your first message. +* **Expensive and complex**: Traditional SMS providers require carrier verification, campaign registration, and number leasing, costing $18-24 before you send your first message. * **Over-engineered**: You don't need marketing features, campaign management, or enterprise infrastructure for simple alerts to yourself and your team. @@ -28,15 +28,15 @@ You need a simple, affordable way to send notifications across multiple channels ## What Notifox Is -Notifox is a **developer-focused multi-channel notification platform** that lets you send alerts to verified recipients (yourself and teammates) with a single API call: +Notifox is a **developer-focused multi-channel notification platform** that lets you send alerts to audiences (yourself and teammates) with a single API call: * **Multiple channels**: Send alerts via SMS ($0.025/part) for urgent notifications, or Email ($0.001/email) for detailed reports. Choose the right channel for each alert. -* **No setup friction**: Since you're only sending to verified recipients, we handle all the complexity. No carrier verification, no number leasing, no campaigns. +* **No setup friction**: Since you're only sending to verified audiences, we handle all the complexity. No carrier verification, no number leasing, no campaigns. -* **Usage-based pricing**: Pay only for what you send—SMS at $0.025 per part, Email at $0.001 per email. No monthly fees, no minimums, no hidden costs. +* **Usage-based pricing**: Pay only for what you send: SMS at $0.025 per part, Email at $0.001 per email. No monthly fees, no minimums, no hidden costs. -* **Simple verification**: Add recipients by verifying phone numbers and email addresses. Up to 15 verified recipients per account. +* **Simple verification**: Add recipients by verifying phone numbers and email addresses. Up to 15 audiences per account. * **Built for developers**: Designed specifically for sending critical notifications and alerts, not mass marketing campaigns. @@ -44,7 +44,7 @@ Notifox is a **developer-focused multi-channel notification platform** that lets ## What Notifox Isn't -* **Not a mass marketing platform**: You can only send to verified recipients (up to 15). Not suitable for sending messages to customers, users, or unverified numbers. +* **Not a mass marketing platform**: You can only send to up to 15 audiences. Not suitable for sending messages to customers, users, or unverified numbers. * **Not a replacement for Twilio**: If you need to send to unverified numbers, create marketing campaigns, or send thousands of messages, Twilio or AWS SNS are better fits. @@ -108,3 +108,13 @@ curl -X POST https://api.notifox.com/alert \ 5. **Send your first alert** using the API, SDK, or interactive console Get started in minutes, not days. No carrier verification, no campaigns, no enterprise sales calls. Just simple, multi-channel notifications that work. + +## Reference Documentation + +For complete API and technical documentation: + +* **[Data Model](/docs/reference/data-model)** - Complete overview of accounts, API tokens, audiences, alerts, channels, and how they relate. Essential for understanding core concepts. +* **[Alerts API Reference](/docs/reference/alerts-api)** - Complete API documentation: endpoints, request/response formats, error codes, rate limits, and examples. +* **[SMS Parts Reference](/docs/reference/parts)** - Understanding SMS parts, encoding (GSM-7 vs UCS-2), character limits, and cost calculation. + +These reference pages provide detailed technical information for both humans and AI assistants. diff --git a/docs/reference/alerts-api.md b/docs/reference/alerts-api.md index d896e27..6b5c92d 100644 --- a/docs/reference/alerts-api.md +++ b/docs/reference/alerts-api.md @@ -26,7 +26,7 @@ The request body must be valid JSON containing: * `audience` (string, required) * The name of the audience to send the alert to * Must match a verified audience name in your account - * Case-insensitive + * Case-sensitive (e.g., `"joe"` and `"Joe"` are different audiences) * `alert` (string, required) * The message text you want to send * Cannot be empty @@ -41,7 +41,7 @@ The request body must be valid JSON containing: | Feature | SMS | Email | |---------|-----|-------| | Cost | $0.025 per part | $0.001 per email | -| Max length | ~765 chars (5 parts) | 50,000 characters | +| Max length | 765 chars (5 parts) | 50,000 characters | | Rate limit | 5 per 5 minutes | 100 per 5 minutes | | Encoding | GSM-7 or UCS-2 | UTF-8 | | Prefix/Footer | "Notifox: " prefix | Footer disclaimer | @@ -125,7 +125,8 @@ On success, you'll receive a `200 OK` response with a JSON body: **Part limits:** * **Single-part**: Up to 160 characters (GSM-7) or 70 characters (UCS-2) * **Multi-part**: 153 characters per additional part (GSM-7) or 67 characters (UCS-2) -* **Total maximum**: ~765 characters (GSM-7) or ~335 characters (UCS-2) +* **Total maximum**: Exactly 765 characters (GSM-7) or ~335 characters (UCS-2) + * For 5-part messages: 5 × 153 = 765 characters (all parts use 153 in multipart SMS) See [SMS Parts and Message Length](/docs/reference/parts) for detailed information. @@ -192,7 +193,7 @@ If you exceed these limits, you'll receive a `429 Too Many Requests` response. |---------|-------| | `alert message cannot be empty` | The `alert` field is missing or empty | | `alert message cannot be empty or only whitespace` | Message contains only spaces/newlines (email) | -| `alert message cannot be greater than 5000 characters` | SMS message exceeds 5000 chars | +| `alert message cannot be greater than 765 characters` | SMS message exceeds 765 chars (5 parts maximum) | | `alert message cannot be greater than 50000 characters` | Email message exceeds 50,000 chars | | `alert message contains invalid UTF-8 encoding` | Email contains invalid UTF-8 characters | | `alert message cannot contain null bytes` | Email contains null (`\x00`) characters | @@ -322,3 +323,7 @@ On success, you'll receive a `200 OK` response with a JSON body: | `400` | Bad Request | Invalid request format or empty alert | | `500` | Internal Server Error | Server-side error occurred | +## Related Reference Documentation + +* [Data Model](/docs/reference/data-model) - Complete overview of alerts, audiences, channels, and how objects relate +* [SMS Parts Reference](/docs/reference/parts) - Understanding SMS parts, encoding, character limits, and cost calculation diff --git a/docs/reference/data-model.md b/docs/reference/data-model.md new file mode 100644 index 0000000..2a2d77e --- /dev/null +++ b/docs/reference/data-model.md @@ -0,0 +1,177 @@ +--- +sidebar_position: 1 +--- + +# Data Model + +This document describes the core objects and concepts in Notifox and how they relate to each other. + +**This is the primary reference for understanding Notifox's object model.** It defines all core concepts including accounts, API tokens, audiences, alerts, and channels with precise types, formats, and relationships. + +## Core Objects + +### Account +Your Notifox account is the top-level container for all resources. + +**Properties:** +- **Balance**: Prepaid balance in USD used to pay for alerts +- **API Tokens**: Authentication credentials for API access (up to 10 per account) +- **Audiences**: Named contacts that can receive alerts (up to 15 per account) + +**Where to find it:** [Console Account page](https://console.notifox.com/?view=account) + +### API Token +An API token (also called API key) is used to authenticate API requests. + +**Type:** String (secret, shown only once when created) + +**Format:** Alphanumeric string, typically 40+ characters + +**Properties:** +- **Token ID**: Unique identifier (visible in dashboard) +- **Created Date**: When the token was created +- **Masked Value**: First and last few characters (for security) + +**Where to create:** [Console API Tokens page](https://console.notifox.com/?view=token) + +**Usage:** Include in `Authorization: Bearer ` header for all API requests + +**Limits:** Maximum of 10 API tokens per account + +### Audience +An audience is a **named identifier (slug)** that maps to verified contact methods (at most one phone number and/or one email address). + +**Type:** String (slug/identifier) + +**Format:** +- Letters, numbers, hyphens, and underscores +- No spaces +- Case-sensitive +- Examples: `joe`, `oncall`, `dev-team`, `support_team` + +**Properties:** +- **Name**: The audience identifier (e.g., `"joe"`, `"oncall"`) +- **Phone Number**: One verified phone number (for SMS alerts), or none +- **Email Address**: One verified email address (for email alerts), or none +- **Verification Status**: Whether each contact method is verified + +**Where to create:** [Console Audiences page](https://console.notifox.com/?view=audiences) + +**Important:** +- An audience is **not** a user ID, email address, or phone number +- It's a **slug/identifier** you choose that represents a contact +- An audience can have **at most one phone number** and **at most one email address** +- An audience can have just a phone number, just an email address, or both +- You must verify at least one contact method (phone or email) before sending alerts to that channel + +**Example:** +```json +{ + "name": "joe", + "phone_number": "+15551234567", + "email_address": "joe@example.com", + "phone_verified": true, + "email_verified": true +} +``` + +### Alert +An alert is a message sent through the Notifox API to a specific audience via a chosen channel. + +**Type:** Object/Request + +**Properties:** +- **audience** (required): String - The audience identifier/slug (e.g., `"joe"`, `"oncall"`) +- **alert** (required): String - The message content +- **channel** (required): String - Either `"sms"` or `"email"` + +**Response Properties:** +- **message_id**: UUID - Unique identifier for the sent alert +- **parts**: Integer - Number of SMS parts (1-5 for SMS, always 1 for email) +- **cost**: Float - Cost in USD +- **currency**: String - Always `"USD"` +- **encoding**: String - `"GSM-7"`, `"UCS-2"` (SMS), or `"UTF-8"` (email) +- **characters**: Integer - Character count + +**Example Request:** +```json +{ + "audience": "joe", + "channel": "sms", + "alert": "Server is down!" +} +``` + +### Channel +A channel is the delivery method for an alert. + +**Types:** +- **`sms`**: SMS text message + - Cost: $0.025 per part + - Max length: 765 characters (5 parts, 5 × 153 = 765) + - Requires: Verified phone number on the audience + - Best for: Urgent, time-sensitive alerts + +- **`email`**: Email message + - Cost: $0.001 per email + - Max length: 50,000 characters + - Requires: Verified email address on the audience + - Best for: Detailed reports, logs, non-urgent notifications + +**Important:** +- You must specify the channel when sending an alert +- The audience must have a verified contact method for the chosen channel +- You can configure both channels on the same audience and choose per-message + +## Relationships + +``` +Account +├── API Tokens (1-10) +├── Audiences (1-15) +│ ├── Phone Number (0 or 1, verified) +│ └── Email Address (0 or 1, verified) +└── Balance (USD) + +Alert Request +├── Uses: API Token (for authentication) +├── Targets: Audience (by slug/identifier) +├── Delivers via: Channel (sms or email) +└── Requires: Verified contact method matching channel +``` + +## Workflow + +1. **Create Account** → Get access to console +2. **Add Funds** → Prepay balance for alerts +3. **Create API Token** → Get authentication credential +4. **Create Audience** → Choose a slug/identifier (e.g., `"joe"`) +5. **Verify Contact Methods** → Add and verify phone number and/or email +6. **Send Alert** → Use API with audience slug, channel, and message + +## Key Concepts + +### Audience vs Contact Method +- **Audience**: The identifier/slug you use in API calls (e.g., `"joe"`) +- **Contact Method**: The actual phone number or email address that receives alerts +- One audience can have at most one phone number and at most one email address +- An audience can have just a phone, just an email, or both +- The audience name is what you reference in API calls, not the contact method + +### Verification +- All contact methods (phone numbers and email addresses) must be verified before use +- Verification ensures you own/control the contact method +- Unverified contact methods cannot receive alerts +- Verification is done via code sent to the contact method + +### Channel Selection +- You choose the channel (`sms` or `email`) when sending each alert +- The audience must have a verified contact method for the chosen channel +- You can send SMS to an audience with only email configured (will fail) +- You can send email to an audience with only phone configured (will fail) +- Best practice: Configure both phone and email on audiences for maximum flexibility + +## Related Reference Documentation + +* [Alerts API Reference](/docs/reference/alerts-api) - Complete API documentation, request/response formats, error codes +* [SMS Parts Reference](/docs/reference/parts) - Understanding SMS parts, encoding, character limits, and cost calculation diff --git a/docs/reference/parts.md b/docs/reference/parts.md index 0b9e084..104dc39 100644 --- a/docs/reference/parts.md +++ b/docs/reference/parts.md @@ -7,7 +7,7 @@ sidebar_position: 1 When you send an SMS alert, Notifox automatically calculates how many **parts** your message will use. Understanding parts helps you predict costs and optimize your message length. :::tip Email alerts are simpler -Email alerts don't have parts—they're always 1 part and cost a flat $0.001 per email, with a maximum of 50,000 characters. This section is specifically about SMS. +Email alerts don't have parts: they're always 1 part and cost a flat $0.001 per email, with a maximum of 50,000 characters. This section is specifically about SMS. ::: ## What Are SMS Parts? @@ -25,13 +25,16 @@ Notifox uses intelligent encoding to fit as much text as possible into each part For messages using standard characters (letters, numbers, basic punctuation, and some accented characters), you get: * **Single-part messages**: Up to 160 characters -* **Multi-part messages**: 153 characters per part after the first part +* **Multi-part messages**: + * 2-part messages: First part up to 160 characters, second part up to 153 characters + * 3+ part messages: All parts use 153 characters each + * **Maximum 5 parts**: Exactly 765 characters (5 × 153 = 765, all parts use 153 in multipart SMS) **Example:** * Message with 80 characters = **1 part** * Message with 160 characters = **1 part** -* Message with 161 characters = **2 parts** (split at 160) -* Message with 315 characters = **3 parts** (160 + 153 + 2 remaining) +* Message with 161 characters = **2 parts** (160 + 1) +* Message with 315 characters = **3 parts** (160 + 153 + 2) **Special Characters That Count Double:** @@ -124,7 +127,7 @@ Length: 155 characters + 10 ("Notifox: ") = 165 characters total Result: 2 parts (160 + 5), $0.050 ``` -### Example 3: Very Long Message (3 Parts) +### Example 3: Longer Message (2 Parts) ``` Message: "This is a very long alert message that exceeds the single SMS limit and will be split into multiple parts when sent to the recipient. Each part costs $0.025." @@ -138,4 +141,9 @@ Result: 2 parts (160 + 31), $0.050 Message: "Alert: Server is down! 🔴" Length: 24 characters + 10 ("Notifox: ") + emoji uses more bytes Result: 1 part (but using UCS-2 encoding due to emoji), $0.025 -``` \ No newline at end of file +``` + +## Related Reference Documentation + +* [Data Model](/docs/reference/data-model) - Complete overview of alerts, channels, and the object model +* [Alerts API Reference](/docs/reference/alerts-api) - Complete API documentation for sending alerts \ No newline at end of file diff --git a/docusaurus.config.js b/docusaurus.config.js index 0006b45..0e10d8d 100644 --- a/docusaurus.config.js +++ b/docusaurus.config.js @@ -25,6 +25,7 @@ const config = { // For GitHub pages deployment, it is often '//' baseUrl: '/', + trailingSlash: true, // GitHub pages deployment config. // If you aren't using GitHub pages, you don't need these. organizationName: 'notifoxhq', // Usually your GitHub org/user name. diff --git a/sidebars.js b/sidebars.js index d79bd8d..fe120fc 100644 --- a/sidebars.js +++ b/sidebars.js @@ -43,6 +43,7 @@ const sidebars = { label: 'Reference', collapsed: false, items: [ + 'reference/data-model', 'reference/parts', 'reference/alerts-api', ],