Send emails with the REST API

Use this guide to send one server-side transactional email and confirm its lifecycle in Apollo Signal.

Replace every mail.company.com example with a domain that is verified in your project.

Create a sending key

Open API keys in Apollo Signal. Create a key with Emails: Send permission, copy it once, and store it in a server-side secret.

Verify the From domain

Open Domains, add the sending domain, publish the required DNS records, and wait for the domain to show as verified.

Set the API key

Export the key in your current shell. Use your deployment secret manager in production:

export SIGNAL_API_KEY=ap_signal_...

Send the message

curl --request POST https://api.signal.apollodeploy.com/v1/emails \
  --header "Authorization: Bearer $SIGNAL_API_KEY" \
  --header "Content-Type: application/json" \
  --data '{
    "from": "auth@mail.company.com",
    "to": "alex@example.com",
    "subject": "Reset your password",
    "text": "Use the secure link in your account to choose a new password."
  }'

Required values

Value	Requirement
API key	Must belong to the active project and include `emails:send`. REST requests use `Authorization: Bearer <key>`. SMTP uses the key as the password.
From	Must use a verified sending domain in the same project. A display name is optional.
To	Must be a valid recipient address for this first send. Keep recipient input on the server and validate it before use.
Content	Include a non-empty subject and at least one of `html` or `text`.

Understand the response

A successful request returns HTTP 201 Created. The returned ID identifies the accepted message and lets you correlate dashboard activity, API reads, and webhook events. A normal immediate send starts in queued. A future send starts in scheduled. A request with testMode: true is recorded as a test instead of reaching a provider.

Check the message

Open Emails and select the message. Check its current status, recipient, timestamps, provider response, content preview, and event timeline. Delivery events are asynchronous, so do not treat the initial API or SMTP acceptance as final delivery.

Common failures

Symptom	What to check
`401 Unauthorized`	The key is missing, malformed, expired, or no longer active.
`403 Forbidden`	The key does not include `emails:send` or belongs to another project.
Validation error	The From domain is unverified, the recipient is invalid, or both `html` and `text` are missing.
`429 Too Many Requests`	Slow down, respect the response headers, and retry with backoff.
Accepted but not delivered	Open the email timeline and check for bounce, complaint, suppression, rejection, or provider failure.

Production checklist

Keep the API key in a secret manager.
Use a restricted key dedicated to this service.
Add an idempotencyKey when your job runner can retry the same logical send.
Configure signed webhooks for final delivery outcomes.
Monitor bounce, complaint, suppression, and quota signals in the dashboard.

Email API

Review every send field and response.

Manage emails

Learn the statuses and troubleshooting workflow.

Getting started

Dashboard

Emails

Contacts and consent

Insights

Domains

Webhooks

Settings

Migration

Send emails with the REST API

Required values

Understand the response

Check the message

Common failures

Production checklist

Email API

Manage emails

​Required values

​Understand the response

​Check the message

​Common failures

​Production checklist

Email API

Manage emails

Required values

Understand the response

Check the message

Common failures

Production checklist