Everything you need to get Margo up and running.
Create an account and get your API key. The API key authenticates all requests to the Margo API.
1. Register a new tenant
POST /api/v1/tenants/
{
"company_name": "Acme Inc",
"brand_voice": "Friendly, professional, concise"
}
# Response
{
"api_key": "mg_live_abc123...",
"tenant": {
"slug": "acme-inc",
"plan": "free"
}
}2. Use your API key in all requests
# Pass your API key via the X-API-Key header curl -H "X-API-Key: mg_live_abc123..." \ https://api.margo.so/api/v1/tenants/me
Margo sends and receives email through your own mailbox via SMTP and IMAP. This keeps deliverability under your control and ensures replies come back to you.
Configure your mailbox
POST /api/v1/email/config
{
"smtp_host": "smtp.yourmail.com",
"smtp_port": 587,
"smtp_username": "agent@yourcompany.com",
"smtp_password": "app-specific-password",
"imap_host": "imap.yourmail.com",
"imap_port": 993,
"imap_username": "agent@yourcompany.com",
"imap_password": "app-specific-password",
"from_name": "Sarah from Acme",
"from_email": "agent@yourcompany.com"
}Credentials are encrypted at rest. Margo never stores plaintext passwords.
Point Margo at your customer database so it can identify who needs outreach and personalize every message.
Add a datasource
POST /api/v1/datasources
{
"type": "postgres",
"connection_string": "postgresql://readonly:pass@db.example.com:5432/myapp",
"description": "Production customer database",
"tables": ["users", "subscriptions", "feature_usage"]
}We strongly recommend using a read-only database user. Margo only needs SELECT access.
Skills let Margo take action on behalf of your customers by calling your API endpoints. Register any endpoint and Margo decides when to use it.
Register a skill
POST /api/v1/skills
{
"name": "extend_trial",
"description": "Extend a customer's free trial by N days",
"endpoint": "https://api.yourapp.com/trials/extend",
"method": "POST",
"auth_type": "bearer",
"auth_token": "sk-your-api-key",
"when_to_use": "When a customer's trial is about to expire and they haven't fully explored the product",
"parameters": {
"customer_id": "string",
"days": "integer"
}
}Supported authentication types
| Type | Header sent | Use case |
|---|---|---|
| none | No auth header | Public endpoints |
| bearer | Authorization: Bearer <token> | OAuth / JWT APIs |
| api_key | X-API-Key: <key> | Key-based APIs |
| basic | Authorization: Basic <base64> | Legacy systems |
Configure how Margo sounds when it writes emails. The brand voice is used as context for every outbound message.
Update brand voice
PATCH /api/v1/tenants/me
{
"brand_voice": "We're a developer tools company. Be technical but approachable. Use short sentences. Never use exclamation marks. Reference specific product features by name. Sign off as 'The Acme Team'."
}Tips
All endpoints require the X-API-Key header. Base URL: /api/v1
| Method | Endpoint | Description |
|---|---|---|
| POST | /tenants/ | Register a new tenant |
| GET | /tenants/me | Get current tenant info |
| PATCH | /tenants/me | Update tenant settings |
| POST | /email/config | Configure mailbox |
| GET | /email/config | Get email config |
| GET | /email/threads | List email threads |
| POST | /skills | Create a skill |
| GET | /skills | List all skills |
| PUT | /skills/{id} | Update a skill |
| DELETE | /skills/{id} | Delete a skill |
| POST | /skills/{id}/test | Test a skill |
| POST | /datasources | Add a datasource |
| GET | /datasources | List datasources |
| GET | /agents | List agent configs |
| PATCH | /agents/{type} | Update agent config |
| POST | /agents/{type}/test | Test an agent |
| GET | /audit | Query audit log |