SpaceCRM Send API: SpaceCRM Send API Tutorial: Send Your First Transactional Email in 10 Minutes
Hands-on tutorial for integrating SpaceCRM's Send API in Node.js, Python, and PHP — from API key to first successful send.
Getting started
Generate your API key from SpaceCRM Settings → API Keys. Store it in an environment variable — never hardcode in source code. API keys grant full access to your sending infrastructure, so treat them like passwords.
Base URL: https://api.spacecrm.net/v1. All requests require Authorization: Bearer YOUR_API_KEY header and Content-Type: application/json. The API supports HTTPS only — plaintext HTTP requests are rejected.
Before sending your first email, verify your sending domain is configured in SpaceCRM. The API will reject sends from unconfigured domains. Domain setup takes under 5 minutes and requires adding three DNS records: SPF, DKIM, and DMARC.
Your first API call
POST /v1/emails with body: { from, to, subject, html }. A 200 response returns { id: 'msg_xxx', status: 'queued' }. Works the same in Python and PHP. The from address must match your configured sending domain.
In Node.js, use the built-in fetch API or any HTTP client like axios. The request is a standard REST call with a JSON body. No SDK installation is required — the API follows OpenAPI standards and works with any language that supports HTTP requests.
For Python developers, requests.post() handles the call in three lines. For PHP, use cURL or Guzzle. Check spacecrm.net/api for full SDK installation and endpoint reference with code samples for every major language.
Using SMTP as an alternative
If your application already uses SMTP, SpaceCRM provides an SMTP relay that requires minimal code changes. Host: smtp.spacecrm.net, Port: 587 (TLS) or 465 (SSL), Username: your API key.
SMTP is ideal for legacy systems where rewriting HTTP calls isn't practical. The relay handles IP warmup, reputation monitoring, and bounce processing automatically. Delivery rates match the REST API — both routes use the same sending infrastructure.
Choose the REST API when building new integrations — it provides richer event data, webhook callbacks, and batch sending capabilities. Choose SMTP when integrating with existing applications that already have SMTP clients configured.
Handling webhook events
Register a webhook endpoint in Settings → Webhooks. You receive POST requests for each event: email.delivered, email.opened, email.bounced, email.complained. Always return 200 within 5 seconds — SpaceCRM retries failed webhook deliveries up to 3 times.
Process hard bounces immediately by adding the address to your suppression list. Suppress complained addresses from all future sends — even one complaint after suppression triggers sending limits from inbox providers.
Use webhook events to trigger business logic in your application. For example, when email.delivered fires, update your CRM status. When email.bounced fires, notify the account owner. Event-driven architecture keeps your systems synchronized without polling.
Error handling and production best practices
Handle rate limits gracefully. SpaceCRM enforces rate limits per API key — exceeding them returns a 429 status code with a Retry-After header. Implement exponential backoff to retry requests automatically.
Log every API call and webhook event for debugging. Store request IDs (the id field in API responses) so you can trace delivery issues through SpaceCRM's support team. Structured logging makes troubleshooting production issues significantly faster.
Use sandbox mode for development and testing. The sandbox environment sends to test addresses without consuming your sending quota or affecting your domain reputation. Switch to production only after your integration is fully tested and validated.