Email

Send your application's own email - a helpdesk reply, a portal sign-in code - for a workspace that subscribes to you, without an email provider account of your own.

Who it is from

By default every email leaves from Connect's sending address, support@cosmoops.com, under a display name: the fromName you send, or the workspace's name when you send none. Put your inbound address in replyTo so the customer's answer reaches you.

With the email:send_as scope you may name fromAddress instead - on your application's hosted domain (set by CosmoOps in Console), or on one of the workspace's verified sending domains. Anything else is refused with sending_domain_unverified and nothing is sent: Connect never quietly swaps the From, so the fallback is yours to choose. A domain verified in the last 7 days sends at most 500 emails a day while it warms up. The response's from names the address that was used.

Threads

Mail clients thread on In-Reply-To and References and nothing else. Every send answers the messageId the email actually left under - Connect's mail provider replaces any Message-ID you propose, so store the one in the response, not your own. Reply with headers.inReplyTo set to the message you are answering and headers.references to the thread so far.

Addresses that cannot receive

Connect keeps one suppression list for the whole platform: an address that hard-bounced or marked mail as spam is never sent to again until an operator clears it. Your mail shares that list and that reputation. A suppressed recipient is skipped, the others are sent, and the skipped ones come back in suppressed - show the address as undeliverable rather than retrying, because a retry is skipped the same way.

Budgets

Per key, and per key and recipient - a ticket thread is a few replies an hour. Send an Idempotency-Key with every call: a retried send without one is a second copy in somebody's inbox.

Endpoints

POST /api/v1/application/email/send

Send an email on a workspace's behalf

Scope email:send  ·  Rate limit 120 requests / min per key, 30 requests / hour per key+recipient

Sends your application's own email - a support reply, a portal sign-in code - for a workspace that subscribes to your application. Server-to-server only: a request carrying a member's session token is refused.

Implementation

1. Prerequisite - an API key scoped to email:send.

2. Send - html and text are both required (256 KB each); to and cc take up to 10 addresses each:

curl -X POST https://connect.cosmoops.com/api/v1/application/email/send \
  -H "Authorization: Bearer YOUR_API_KEY_PLAINTEXT" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: ticket-1042-reply-3" \
  -d '{"workspaceId":"WORKSPACE_ID","to":["priya@example.com"],"subject":"Re: Refund for order 1042","html":"<p>Done - it is on its way.</p>","text":"Done - it is on its way.","replyTo":"t-1042@in.example.com","fromName":"Acme Support","headers":{"inReplyTo":"<CAF0x9@mail.gmail.com>","references":"<CAF0x9@mail.gmail.com>"}}'

3. The sender. Without fromAddress, the email leaves from Connect's address (support@cosmoops.com) with fromName as the display name - the workspace's name when you send none. Put your own inbound address in replyTo to receive the answer.

With the email:send_as scope, fromAddress names the sender: any address on your application's hosted domain, or one on the workspace's verified sending domains (/email/domains). An unverified domain is refused with sending_domain_unverified and nothing is sent - re-send without fromAddress if you want Connect's address instead. The response's from is the address actually used.

4. Threading. Store the response's messageId: it is the Message-ID the email actually left under (Connect's mail provider replaces any headers.messageId you send), and a customer's reply names it in In-Reply-To. Send the next reply with headers.inReplyTo and headers.references set from the thread. Header values may not contain line breaks.

5. Suppression. An address that hard-bounced or marked Connect's mail as spam is skipped and listed in suppressed; the rest are sent. When every recipient is suppressed nothing is sent and the call still answers 201 - show the customer's address as undeliverable rather than retrying.

Errors

validation_error (400 - bad body, too many recipients, an oversize body, or a line break in a header value), forbidden (403 - key missing email:send, a session token was forwarded, or your application is not installed in that workspace), from_address_not_allowed (403 - fromAddress without the email:send_as scope), idempotency_key_reused/request_in_progress (409), sending_domain_unverified (409 - fromAddress is not on your hosted domain or a verified sending domain of this workspace; nothing was sent), rate_limited (429 - per key, and per key and recipient), domain_warming_up (429 - a domain verified in the last 7 days has sent its 500 for today; honour Retry-After), delivery_failed (502 - retry).

Request body

Responses

Response body

GET /api/v1/application/email/domains

List a workspace's sending domains

Scope email:domains  ·  Rate limit 60 requests / min per key

Every domain the workspace has registered for sending, each with the DNS records it must publish and whether each one is in place as of the last check. A sending domain belongs to the workspace, not to your application - every application with email:domains sees the same list. Server-to-server only.

Parameters

Responses

Response body

POST /api/v1/application/email/domains

Add a sending domain

Scope email:domains  ·  Rate limit 60 requests / min per key

Registers the workspace's own domain (acme.com) so applications may send From addresses on it, and answers the records to publish. Idempotent: adding a domain the workspace already holds answers the existing one, with its unchanged token.

Records

The domain is verified once the ownership TXT and DKIM both pass. Connect re-checks pending domains every ten minutes for 72 hours and verified ones hourly; a verified domain whose records break is failing (it still sends) and, after 72 hours, failed. The workspace's admins are emailed on each change.

Errors

validation_error (400 - not a domain name), forbidden (403), domain_claimed (409 - another workspace has verified it), conflict (409 - the workspace holds the maximum number of domains), domain_not_allowed (422 - a free-mail provider, a public suffix, or a CosmoOps domain).

Request body

Responses

Response body

GET /api/v1/application/email/domains/{domain}

Get a sending domain

Scope email:domains  ·  Rate limit 60 requests / min per key

One domain as of its last check - no DNS lookup is made. Use POST /email/domains/{domain}/check to re-check now.

Parameters

Responses

Response body

POST /api/v1/application/email/domains/{domain}/check

Re-check a sending domain

Scope email:domains  ·  Rate limit 60 requests / min per key

Checks SES and DNS now and answers the updated domain, with a status on every record (ok, missing, mismatch, unknown). Connect also does this on its own, so there is no need to poll.

Parameters

Request body

Responses

Response body

DELETE /api/v1/application/email/domains/{domain}

Remove a sending domain

Scope email:domains  ·  Rate limit 60 requests / min per key

Removes the domain from the workspace; mail can no longer be sent From it. 204 on success.

Parameters

Responses