Setting up an Email Service involves writing the handler class, configuring the service, generating the address, and testing the end-to-end flow. The steps below cover the full path from zero to a working inbound endpoint.
- Write the Apex handler
Create an Apex class implementing Messaging.InboundEmailHandler. Implement handleInboundEmail to parse the InboundEmail object and write the result to your target sObject. Include error handling and logging.
- Deploy the handler to the target org
Deploy through SFDX or a changeset. Confirm the class compiles and at least one Apex test covers the handler logic; the platform requires test coverage before deployment to production.
- Create the Email Service
Setup > Custom Code > Email Services > New Email Service. Name the service, link to your Apex class, set Active to true.
- Configure failure response
Under Failure Response, choose whether unrecognized senders are bounced, the message is requeued, or discarded silently. Pick Bounce for partner integrations so the sender knows the message did not process.
- Set authorized senders
Under Authorized Senders, list the email addresses or domains that are allowed to send to this address. Leave blank to accept all senders; restrict for partner-only inbound channels.
- Generate the email address
Click New Email Address on the service. Define the local-part, link to a Run As user, save. The platform generates the full address with the hash and apex.salesforce.com domain.
- Test end-to-end
Send a test message to the generated address. Confirm the handler fires (check debug logs), the result is written to the target sObject, and any reply or bounce behaves as expected.
The handler class implementing Messaging.InboundEmailHandler. The core processing logic for the inbound mail.
The Salesforce User the handler runs as. Determines permissions, sharing, and field visibility during execution.
Comma-separated list of allowed addresses or domains. Leave blank to allow any sender; populate for partner-only inbound.
Bounce, Discard, or Requeue. Bounce notifies the sender on processing failure; Discard fails silently; Requeue retries.
Master switch for the service. Set inactive to pause inbound processing without losing the address or configuration.
- Apex governor limits apply per inbound message. A handler doing too many SOQL queries or DML operations hits the limit and fails the message, with no automatic retry unless Failure Response is set to Requeue.
- The Run As user must have permissions to write to the target sObject. A handler running as a low-privilege user silently fails on the DML if record access is missing.
- Email addresses are regenerated on every service activation. Sandbox refreshes or service re-activations produce a new address, which breaks any partner integration pointing at the old one.
- Authorized Senders comparison is case-insensitive but otherwise exact. A pattern like the partner domain works as a wildcard; user at partner domain is exact match only.
- The handler runs synchronously inside the email processing call. Long-running handlers (over a few seconds) risk timeout; offload heavy work to a queueable or future method called from the handler.