Concepts
Choose the right API
Decide when to use the Management API and when to use the Send API.
Qboxmail has two APIs. They work together, but serve different purposes.
Send API requires Delivery setup first
The Send API only works after you have a Delivery account set up. Before using it, make sure the account has at least one configured sending domain and a Send API token. If you still need to create those, use the Management API or the Qboxmail panel first.
| API | What it is for | Typical endpoints | Authentication |
|---|---|---|---|
| Management API | Create, configure, and inspect Hosting and Delivery resources. | /api/domains, /api/delivery/domains, /api/delivery/accounts, /api/delivery/suppression_lists, /api/delivery/tracemail/* | X-Api-Token |
| Send API | Send transactional or newsletter email from an existing Delivery account. | /v1/send, /v1/send/bulk | Authorization: Bearer <API_TOKEN> |
When to use the Management API
- Create or manage Hosting domains.
- Create mailboxes, aliases, domain aliases, signatures, address books, and contacts.
- Manage managers, team members, imports, migrations, and Vault archiving.
- Create Delivery domains and Delivery accounts.
- Manage Delivery suppression lists.
- Read Delivery TraceMail logs, counters, dashboard data, and reports.
When to use the Send API
Use the Send API only after you have a Delivery account, a configured sending domain, and a Send API token.
- Send one transactional message from an existing Delivery account.
- Send a batch of complete messages from an existing Delivery account.
- Send a templated newsletter or campaign to many recipients from an existing Delivery account.
- Send email over HTTP instead of SMTP, after Delivery is set up.
Common decision table
| I want to... | Use |
|---|---|
| Add a new hosted email domain | Management API |
| Create a mailbox for a hosted domain | Management API |
| Create a Delivery domain for outbound sending | Management API |
| Verify Delivery DNS records | Management API |
| Create a Delivery account | Management API |
| Create a Send API token for that Delivery account | Qboxmail panel, from the Delivery account settings |
| Send an email but I do not have a Delivery account yet | Set up Delivery first |
| Send an email but the Delivery domain is not configured yet | Set up Delivery first |
| Send a transactional email from an already configured Delivery account | Send API |
| Send one templated message to many recipients from an already configured Delivery account | Send API |
| Add an address to the suppression list | Management API |
| Check message status and delivery results | Management API TraceMail |
Do not mix the two token types
A Management API token is not valid for /v1/send. A Send API bearer token is not valid for /api/* management endpoints.