Zum Inhalt springen

Mailer protocol

Dieser Inhalt ist noch nicht in deiner Sprache verfügbar.

The services, messages, and enums of the package my.plugin.mailer.v1, which mailer.proto defines.

Sending the server’s email through a service of the operator’s choice, such as a mail provider that offers only an HTTP API. A message can carry a secret, such as a verification link, so a plugin must not log it, and the server refuses plain TCP to this kind.

rpc Send(SendRequest) returns (SendResponse);

Request: SendRequest. Response: SendResponse.

Send sends one message to one recipient. The server calls it from background jobs and retries a failure, so the same message may come twice. It lasts plugin_mailer_timeout at most.

The request holds the parts of the message, not its encoded form. The plugin adds what the server leaves to whoever sends: a Message-ID header (unique per message, on the domain of envelope_from), a Date header, and the header Auto-Submitted: auto-generated, which keeps automatic replies from looping.

  • category (Category, field 1): A name in JSON. A value that a plugin does not know is sent like any other.
  • to (string, field 2): The recipient, one bare address (local@domain) in UTF-8. A plugin whose service needs ASCII converts the domain to Punycode, and answers OUTCOME_INVALID for a local part it cannot send.
  • envelope_from (string, field 3): The sender, one bare address: the mail_from setting of the server.
  • from_name (string, field 4): The display name of the sender, one line; empty sends the bare address.
  • reply_to (string, field 5): The address that replies go to, one bare address; empty adds no Reply-To.
  • subject (string, field 6): The subject, one line of UTF-8.
  • text (string, field 7): The plain-text body in UTF-8, with “\n” line ends.
  • html (string, field 8): The HTML body in UTF-8; empty sends the plain text only.
  • headers (map of string to string, field 9): Headers to add by their canonical name. The server sends only List-Unsubscribe and List-Unsubscribe-Post, one line each.
  • outcome (Outcome, field 1): A name in JSON. Anything but a value below, an empty response included, is a temporary failure: the server sends the message again later.
  • enhanced_status (string, field 2): The enhanced status code (RFC 3463) of a refusal, such as 5.1.1, if the service names one. The server keeps a code of class 5 of a rejection and of class 4 of OUTCOME_TEMPORARY, and ignores anything else: it takes no text of the service.

The kind of a message.

  • CATEGORY_UNSPECIFIED = 0
  • CATEGORY_TRANSACTIONAL = 1: A verification, a password reset, or another message that nobody can unsubscribe from.
  • CATEGORY_NOTIFICATION = 2
  • CATEGORY_ANNOUNCEMENT = 3

The result of a call. Connect errors say only that the call failed in transport, which the server retries like OUTCOME_TEMPORARY.

  • OUTCOME_UNSPECIFIED = 0
  • OUTCOME_SENT = 1: The service took the message.
  • OUTCOME_INVALID = 2: The message cannot be sent as it is, such as a recipient that is not an address. The server does not send it again.
  • OUTCOME_RECIPIENT_REJECTED = 3: The address does not exist. The server does not send it again, and stops emailing the address.
  • OUTCOME_REJECTED = 4: The service refused the message for good, for another reason. The server does not send it again.
  • OUTCOME_TEMPORARY = 5: The service refused the message for now, or did not answer. The server sends it again later.

Für LLMs und Coding-Agenten:llms.txt,llms-full.txt, llms-small.txt

Analyse auf dieser Website