API Reference

The NotiGrid API is organized around REST. Our API accepts JSON-encoded request bodies and returns JSON-encoded responses.

Base URL

https://api.notigrid.com

Authentication

All API requests require authentication using an API key. Include your API key in the Authorization header:

Authorization: Bearer YOUR_API_KEY

Keep your API keys secure. Never commit them to version control or expose them in client-side code.

Endpoints

Send Notification

Send a notification via any channel.

POST/v1/notify

Request Body

Field	Type	Required	Description
`channel`	string	Yes	Channel type: `email`, `sms`, `push`, `slack`
`to`	string	Yes	Recipient (email, phone, or device token)
`subject`	string	No	Message subject (email only)
`body`	string	Yes	Message content
`template`	string	No	Template ID to use
`variables`	object	No	Variables for template rendering

Example Request

curl -X POST https://api.notigrid.com/v1/notify \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type": application/json" \
  -d '{
    "channel": "email",
    "to": "user@example.com",
    "subject": "Welcome!",
    "body": "Thanks for signing up."
  }'

Response

{
  "id": "notif_1234567890",
  "status": "queued",
  "channel": "email",
  "to": "user@example.com",
  "createdAt": "2025-01-16T10:30:00Z"
}

List Templates

Get all templates for your organization.

GET/admin/templates

Query Parameters

Parameter	Type	Required	Description
`orgId`	string	Yes	Organization ID

Example Request

curl -X GET "https://api.notigrid.com/admin/templates?orgId=org_123" \
  -H "Authorization: Bearer YOUR_API_KEY"

Response

{
  "items": [
    {
      "id": "tpl_123",
      "name": "welcome-email",
      "channel": "email",
      "subject": "Welcome {{name}}!",
      "body": "Hi {{name}}, thanks for joining!",
      "createdAt": "2025-01-15T12:00:00Z"
    }
  ]
}

Create Template

Create a new notification template.

POST/admin/templates

Request Body

Field	Type	Required	Description
`name`	string	Yes	Template name (unique)
`channel`	string	Yes	Channel type
`subject`	string	No	Email subject (email only)
`body`	string	Yes	Message template with {{variables}}
`description`	string	No	Template description

Example Request

curl -X POST https://api.notigrid.com/admin/templates?orgId=org_123 \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "password-reset",
    "channel": "email",
    "subject": "Reset your password",
    "body": "Click here to reset: {{resetLink}}"
  }'

Get Logs

Retrieve notification delivery logs.

GET/admin/logs

Query Parameters

Parameter	Type	Required	Description
`orgId`	string	Yes	Organization ID
`limit`	number	No	Number of results (max 100)
`offset`	number	No	Pagination offset
`channel`	string	No	Filter by channel
`status`	string	No	Filter by status

Example Request

curl -X GET "https://api.notigrid.com/admin/logs?orgId=org_123&limit=10" \
  -H "Authorization: Bearer YOUR_API_KEY"

Rate Limits

API requests are rate limited based on your subscription plan:

Plan	Rate Limit
Free	10 requests/second
Pro	50 requests/second
Team	100 requests/second
Scale	Custom

Rate limit headers are included in all responses:

X-RateLimit-Limit: 50
X-RateLimit-Remaining: 45
X-RateLimit-Reset: 1642348800

Error Codes

Code	Description
`400`	Bad Request - Invalid parameters
`401`	Unauthorized - Invalid API key
`403`	Forbidden - Insufficient permissions
`404`	Not Found - Resource doesn't exist
`429`	Too Many Requests - Rate limit exceeded
`500`	Internal Server Error

Error Response Format

{
  "error": "Invalid API key",
  "code": "INVALID_API_KEY",
  "statusCode": 401
}

Webhooks

Configure webhooks to receive real-time notifications about delivery events.

Event Types

notification.sent - Notification successfully sent
notification.delivered - Notification delivered to recipient
notification.failed - Notification failed to send
notification.opened - Email opened (tracking enabled)
notification.clicked - Link clicked (tracking enabled)

Webhook Payload

{
  "event": "notification.delivered",
  "data": {
    "id": "notif_123",
    "channel": "email",
    "to": "user@example.com",
    "status": "delivered",
    "timestamp": "2025-01-16T10:35:00Z"
  }
}

Webhook endpoints must respond with a 200 status code within 5 seconds.

API Reference

On this page