mailer/api/mailer/mailer.proto

// Copyright 2021 The LUCI Authors.
//
// Licensed under the Apache License, Version 2.0 (the "License");
// you may not use this file except in compliance with the License.
// You may obtain a copy of the License at
//
//      http://www.apache.org/licenses/LICENSE-2.0
//
// Unless required by applicable law or agreed to in writing, software
// distributed under the License is distributed on an "AS IS" BASIS,
// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
// See the License for the specific language governing permissions and
// limitations under the License.

syntax = "proto3";

package luci.mailer.v1;

import "google/api/field_behavior.proto";

option go_package = "go.chromium.org/luci/mailer/api/mailer";


// Mailer can send emails.
//
// Authentication happens via ID tokens.
service Mailer {
  // SendMail enqueues an email for sending.
  //
  // On OK RPC status code, the email was enqueued and will eventually be sent.
  // The response contains an opaque identifier that can be used to trace this
  // operation in logs.
  //
  // Transient error status codes (INTERNAL, UNKNOWN, etc.) indicate that the
  // email may or may not been enqueued. The caller should retry, passing the
  // exact same `request_id`.
  //
  // Non-retryable errors (per https://google.aip.dev/194) indicate that the
  // email was rejected and retries won't help.
  rpc SendMail(SendMailRequest) returns (SendMailResponse);
}


// SendMailRequest is passed to SendMail RPC and contains the email to send.
//
// Addresses may be of any form permitted by RFC 822. At least one of To, Cc,
// or Bcc must be non-empty.
//
// At least one of TextBody or HtmlBody must be non-empty.
message SendMailRequest {
  // A unique identifier for this request to guarantee idempotency.
  //
  // Restricted to 36 ASCII characters. A random UUID is recommended. This
  // request is only idempotent if a `request_id` is provided.
  string request_id = 1;

  // Sender is put into "From" email header field.
  //
  // The server will validate this field and reject requests that use disallowed
  // values (based on the authenticated identity of the caller).
  string sender = 2 [ (google.api.field_behavior) = REQUIRED ];

  // ReplyTo is put into "Reply-To" email header field.
  string reply_to = 3;

  // To is put into "To" email header field.
  repeated string to = 4;

  // Cc is put into "Cc" email header field.
  repeated string cc = 5;

  // Bcc is put into "Bcc" email header field.
  repeated string bcc = 6;

  // Subject is put into "Subject" email header field.
  string subject = 7 [ (google.api.field_behavior) = REQUIRED ];

  // TextBody contains a plaintext body of the email message.
  string text_body = 8;

  // HtmlBody contains an HTML body of the email message.
  string html_body = 9;
}


// SendMailResponse is returned by SendMail RPC.
message SendMailResponse {
  // MessageId as an opaque identifier of the enqueued email.
  string message_id = 1;
}