blob: da448c237864eef05c35df769ae67e25c7606b56 [file] [log] [blame]
// 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
// Unless required by applicable law or agreed to in writing, software
// distributed under the License is distributed on an "AS IS" BASIS,
// 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 = "";
// 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 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;