PranavNagrecha/AwesomeSalesforceSkills / skills/admin/email-service-inbound
email-service-inbound
VerifiedInbound email processing in Salesforce via Email Services + the `Messaging.InboundEmailHandler` Apex interface. Covers EmailService configuration (running user, accept-from address, attachment handling, error / failure routing), the EmailServicesAddress per-routing-address pattern, the handler's `Messaging.InboundEmail` payload (text body, HTML body, headers, attachments, in-reply-to threading), and the canonical Email-to-Case alternative for case creation. NOT for outbound email (use admin/email-templates-and-alerts), NOT for Email-to-Case flow customization itself (use admin/email-to-case-configuration). Trigger keywords: EmailServicesFunction, EmailServicesAddress, runAsUser, localPart, EmailDomainName, attachmentOption, overLimitAction, errorRoutingAddress, routing address, inbound email limit.
| File | Kind | Size |
|---|---|---|
| SKILL.md | skill md | 26.5 KB |
| references/examples.md | markdown | 7.0 KB |
| references/gotchas.md | markdown | 15.3 KB |
| references/llm-anti-patterns.md | markdown | 7.4 KB |
| references/metadata-examples.md | markdown | 16.7 KB |
| references/well-architected.md | markdown | 7.1 KB |
| scripts/check_email_service_inbound.pyexecutable | script | 15.4 KB |
| templates/email-service-inbound-template.md | markdown | 2.5 KB |
references/examples.md
View on GitHub# Examples — Inbound Email Service
## Example 1 — Returning `success = false` exposes a stack trace
**Wrong code** (catch-block excerpt from the handler).
```apex
} catch (Exception ex) {
res.success = false;
res.message = ex.getMessage() + '\n' + ex.getStackTraceString();
return res;
}
```
**What goes wrong.** The sender (potentially anonymous public)
receives a bounce-back containing the Apex stack trace —
information disclosure.
**Right code** (catch-block excerpt from the handler).
```apex
} catch (Exception ex) {
ApplicationLogger.error('Inbound email failed', ex);
res.success = false;
res.message = 'We could not process your email. Please contact support@acme.com if this persists.';
return res;
}
```
Friendly message to the sender; full stack trace logged for the
admin.
---
## Example 2 — Threading via subject token
**Context.** Outbound emails carry `[Acme:Case-12345]` in the
subject. Inbound replies preserve the token. Custom service uses
it to thread to the existing Case.
```apex
private static Pattern TOKEN_RE = Pattern.compile('\\[Acme:Case-(\\d+)\\]');
private static Id resolveCaseFromSubject(String subject) {
if (subject == null) return null;
Matcher m = TOKEN_RE.matcher(subject);
if (!m.find()) return null;
String caseNumber = m.group(1);
List<Case> cs = [SELECT Id FROM Case WHERE CaseNumber = :caseNumber LIMIT 1];
return cs.isEmpty() ? null : cs[0].Id;
}
```
Subject tokens survive client mangling better than header threading, but
they are the *fallback*, not the first attempt: the platform already parses
the RFC 2822 identifiers into `email.messageId`, `email.inReplyTo` and
`email.references`, so try those first and fall through to the token only
when the chain is broken.
```apex
private static Id resolveCase(Messaging.InboundEmail email) {
Set<String> parents = new Set<String>();
if (String.isNotBlank(email.inReplyTo)) parents.add(email.inReplyTo);
if (email.references != null) parents.addAll(email.references);
if (!parents.isEmpty()) {
List<EmailMessage> prior = [
SELECT ParentId FROM EmailMessage
WHERE MessageIdentifier IN :parents AND ParentId != null
WITH USER_MODE ORDER BY MessageDate DESC LIMIT 1
];
if (!prior.isEmpty()) return prior[0].ParentId;
}
return resolveCaseFromSubject(email.subject); // token fallback
}
```
`EmailMessage.MessageIdentifier` is the object-reference field that stores
"the ID of the email message" and is `idLookup`-enabled, which is what
makes this lookup possible on the standard object.
---
## Example 3 — Allow-list-driven anti-spam
**Context.** Public address `quotes@inbound.acme.com` receives spam.
**Approach.** Custom Metadata Type `Allowed_Email_Domain__mdt` with
records like `acme.com`, `partner-vendor.com`. Handler checks
sender's domain against the list:
```apex
private static Set<String> allowedDomains() {
Set<String> out = new Set<String>();
for (Allowed_Email_Domain__mdt d : Allowed_Email_Domain__mdt.getAll().values()) {
out.add(d.Domain__c.toLowerCase());
}
return out;
}
```
Admin-editable list; no Apex redeploy when a new partner needs
access.
---
## Example 4 — Attachment storage policy
**Wrong instinct.** Save every binary attachment to ContentVersion
without size / type / count checks.
**What goes wrong.** Spammer sends 10 MB attachments daily for
months; org's File Storage allocation fills up; legitimate file
operations start failing.
**Right policy.** Two layers. The platform layer filters before Apex
runs, via `attachmentOption` on the `EmailServicesFunction`
(`None` | `NoContent` | `TextOnly` | `BinaryOnly` | `All`); the Apex layer
enforces size, count and MIME type on what survives. Drive the thresholds
from Custom Metadata so a policy change is a data deploy, not a code
deploy.
```apex
/**
* Attachment admission policy. Returns the reason an attachment was
* refused, or null when it is acceptable. Thresholds live in
* Email_Intake_Policy__mdt so admins can tune them without Apex.
*/
public with sharing class AttachmentPolicy {
private final Integer maxBytes;
private final Integer maxCount;
private final Set<String> allowedMimeSubTypes;
public AttachmentPolicy(String policyName) {
Email_Intake_Policy__mdt p = Email_Intake_Policy__mdt.getInstance(policyName);
this.maxBytes = (Integer) (p.Max_Attachment_MB__c * 1024 * 1024);
this.maxCount = (Integer) p.Max_Attachments_Per_Email__c;
this.allowedMimeSubTypes = new Set<String>();
for (String s : p.Allowed_Mime_Types__c.split(',')) {
this.allowedMimeSubTypes.add(s.trim().toLowerCase());
}
}
public Integer maxAttachments() {
return this.maxCount;
}
/** null => accept. Non-null => the audit reason for refusing. */
public String refuse(Messaging.InboundEmail.BinaryAttachment att) {
// attachmentOption = NoContent hands over metadata with a null body.
if (att.body == null) {
return 'no body (service is set to NoContent, or the part was empty)';
}
if (att.body.size() > this.maxBytes) {
return 'over ' + this.maxBytes + ' bytes';
}
String mime = att.mimeTypeSubType == null
? ''
: att.mimeTypeSubType.toLowerCase();
if (!this.allowedMimeSubTypes.contains(mime)) {
return 'MIME type ' + mime + ' not allow-listed';
}
return null;
}
}
```
Refusals are audit events, not errors: log the reason against the parent
record and still return `success = true`, so the sender is not bounced for
attaching a signature image.
| Layer | Control | Where it lives |
|---|---|---|
| Platform | Accept none / metadata-only / text / binary / all | `attachmentOption` in `emailservices/*.xml` |
| Platform | Text attachments delivered as Blob instead of String | `isTextAttachmentsAsBinary` |
| Apex | Per-attachment byte cap | `Email_Intake_Policy__mdt.Max_Attachment_MB__c` |
| Apex | Per-email count cap | `Email_Intake_Policy__mdt.Max_Attachments_Per_Email__c` |
| Apex | MIME allow-list | `Email_Intake_Policy__mdt.Allowed_Mime_Types__c` |
| Operations | Retention / archive of stored files | Documented, with an owner and a review date |
The ~25 MB per-message ceiling is not one of these layers — it is enforced
by the platform before the handler runs, and is not configurable (see
`gotchas.md` § 4).
---
## Anti-Pattern: Doing a synchronous callout in the handler
```apex
HttpRequest req = new HttpRequest();
req.setEndpoint('https://crm-extension.example.com/notify');
req.setMethod('POST');
new Http().send(req); // synchronous, in the handler
```
**What goes wrong.** Inbound email volume spikes; every email
makes a callout; callout latency (or failure) blocks email
processing; emails stack up in the platform's incoming queue.
**Correct.** Publish a Platform Event from the handler; an Apex
subscriber does the callout asynchronously. The handler returns
`success = true` immediately; the callout happens later.
Related skills
| Skill | Stars | Updated | Works with | Status | Install |
|---|---|---|---|---|---|
| slack-gif-creatoranthropics/skillsKnowledge and utilities for creating animated GIFs optimized for Slack. Provides constraints, validation tools, and animation concepts. Use when users request animated GIFs for Slack like "make me a GIF of X doing Y for Slack." | Stars: 198k | Updated | Claude CodeCodex | Verified | Install |
| ponytailDietrichGebert/ponytailLazy senior dev mode for any coding task: the smallest change that fully solves it, and a reply a busy human understands in one read. | Stars: 194k | Updated | Claude CodeCodex | Verified | Install |
| ponytail-debtDietrichGebert/ponytailHarvest every shortcut: comment into one debt ledger, so deferrals get tracked instead of forgotten. One-shot report. | Stars: 194k | Updated | Claude CodeCodex | Verified | Install |
| ponytail-debtDietrichGebert/ponytailList every `shortcut:` comment (and older `ponytail:` ones) as a debt ledger. One-shot report, changes nothing. Use for "ponytail debt", "what did ponytail defer", "list the shortcuts", /ponytail-debt. | Stars: 194k | Updated | Claude CodeCodex | Verified | Install |