Write by email
A case can run over email. A case is an email case when it has an email thread: sender address, contact address, subject and the context the agent needs.
1. Add and verify a sender domain
Use a subdomain you own, such as mail.acme.com.
The response lists the DNS records to add: three CNAME records for DKIM and one MX record that routes replies to Lelemon. The domain is pending until your DNS answers and becomes verified on its own; POST /v2/email/domains/{id}/verify (or a GET) checks it right away, and it turns failed if the DKIM records are wrong. Register a subdomain such as mail.acme.com, not your main domain: you send from it and receive on it, and the MX record goes on that same name, so it does not take over the mail of acme.com. inboundAgentId is the agent that opens a case when a stranger writes to an address of the domain. Without it, mail from unknown senders is not routed to an agent.
Keys need email:write.
2. Send the first email
The response is 202. A message goes through queued, sent and then delivered or bounced. A sender or recipient the email service rejects ends as failed with a failure.code such as identity_not_verified, sandbox_recipient_not_verified, message_rejected, sending_paused, account_suspended or throttled. to takes exactly one of contactId, externalRef or email. from must belong to a verified domain and defaults to the first one: 422 sender_domain_not_verified otherwise. The agent in onReply needs the email channel.
You can also open an email case first with POST /v2/cases and "channel": "email", then write with POST /v2/cases/{id}/messages. The first message of the case needs a subject: 422 subject_required otherwise.
Replies
Replies are matched to the thread by In-Reply-To and References against the Message-IDs of the emails Lelemon sent. The sender must be the address of the thread, and the email must pass DMARC. An email with a malformed or repeated From header is ignored. The agent answers like it does on any other channel, and you see the reply as a message.created event.
If a recipient marks an email as spam, the contact is opted out of the email channel, as if they had written stop.
Before every send
Lelemon checks opt-outs for the email channel, by contact and by address, and the recipient allowlist. A blocked send answers 422 contact_opted_out or 422 recipient_not_allowed.