Drive Plumail from a terminal
No agent needed: the REST API is usable directly from a shell or any language. Nothing to install — curl is enough.
Create an API key
In your Plumail workspace: Settings → API → New key. Name it, tick the permissions, save. The key is shown ONCE — copy it immediately. It starts with plm_live_ followed by thirty-two characters.
Store the key in an environment variable
Never in plain text in a shared script. Add the line to your profile file so it survives a terminal restart.
export PLUMAIL_API_KEY="plm_live_…"Check that it's connected
Ask for the account status. This is read-only: nothing is modified, nothing is sent. The response names your workspace and lists your verified sending domains — those are the addresses you can send from.
curl -s https://plumail.fr/api/v1/me \ -H "Authorization: Bearer $PLUMAIL_API_KEY"Send an email
The sending address must be on a verified domain — the previous call told you which ones. The Idempotency-Key header prevents a duplicate send if the command is replayed.
curl -X POST https://plumail.fr/api/v1/emails \ -H "Authorization: Bearer $PLUMAIL_API_KEY" \ -H "Content-Type: application/json" \ -H "Idempotency-Key: test-1" \ -d '{ "from": "[email protected]", "to": "[email protected]", "subject": "Test from the terminal", "text": "It works." }'Next steps
Other endpoints — subscribers, suppression list, campaigns — are documented in the reference, each with a curl example. The OpenAPI file lets you generate a client in your language.
curl -s https://plumail.fr/api/v1 # endpoint map curl -s https://plumail.fr/openapi.json # full technical description
Troubleshooting
Every API error carries a readable code. Here are the ones you encounter when connecting.
| 401 invalid_api_key | The key is incomplete (a newline crept in during copy-paste) or has been replaced. Create a new one. |
|---|---|
| 401 revoked_api_key | The key was cut under Settings → API. Create another one. |
| 403 insufficient_scope | The key does not have the required permission. Permissions are chosen at creation and cannot be changed: create a key with the right scope. |
| 422 unverified_from_domain | The sending address is not on a verified domain in the workspace. The error message lists the ones that are. To add one: Domains → Add a domain, then set the DNS records. |
| 429 rate_limit_exceeded | More than 600 requests per minute for this key. The Retry-After header says how many seconds to wait. |