mailalias-api

View readme on GitLab

mailalias.proto

syntax = "proto3";
package mailalias;

/*
The Mailalias API manages email aliases (more or less "email redirects").

The aliases visible through this API are generally all enabled.
Changes may not take effect immediately on all mail servers,
but should immediately be visible to other API calls.

Aliases are uniquely identified by their source and destination addresses.
The "source" address is the "alias" which doesn't actually have a mailbox.
The "destination" address is the "real address" which email ends up at.

All endpoints require an API key passed in the "authorization" metadata header.
Creating and deleting "locked" aliases requires a privileged API key.

API keys are meant to be used by other applications which need to work with
the people API and should never be given to users. In case an application
(eg. mailalias-ui) needs to authorize users of this API directly, it can use
session tokens instead. Session tokens are passed in the "session" metadata header
(and the "authorization" is not passed). A session token encodes the users
priviliges and has an encoded expiration time (but may expire ealrier).
Session tokens are created by the "UserLogin" RPC.

If no "authorization" or "session" metadata header is passed, or the supplied
token is invalid or expired a "Unauthenticated" error is returned.
*/

service Mailalias {
  // ListAliases returns all existing aliases (supports filtering).
  rpc ListAliases (ListAliasesRequest) returns (stream Alias);

  // CreateAlias creates the specified alias.
  // It is not possible to create an alias A which shadows another alias B.
  // You must explicitly delete the alias B first.
  rpc CreateAlias (CreateAliasRequest) returns (Empty);

  // DeleteAlias deletes the specified alias.
  rpc DeleteAlias (DeleteAliasRequest) returns (Empty);

  // UserLogin is used to get a session token for an authorized user.
  // See the introductory text in mailalias.proto for an explaination of session tokens.
  // If login is unsuccessful a PermissionDenied (7) error is returned and if an internal
  // error occurs a GRPC error will be returned.
  rpc UserLogin (UserLoginRequest) returns (UserLoginResponse);

  // LoginValidation is used to validate a session token for a presumably logged in user.
  // See the introductory text in mailalias.proto for an explanation of session tokens.
  // If validation is unsuccessful a PermissionDenied (7) error is returned and if an internal
  // error occurs a GRPC error will be returned.
  rpc LoginValidation (LoginValidationRequest) returns (Empty);

  rpc SystemStatus (Empty) returns (SystemStatusResponse);
}

message Empty {}

message Alias {
  // Email going to the "source" address is sent to the "destination" address.
  // This should be a VIS-controlled address, for example "vorstand@vis.ethz.ch"
  string source = 1;

  // The "destination" address receives all email which was sent to the "source" address.
  // This may or may not be a VIS-controlled address, for example "jdoe@vis.ethz.ch" or "jdoe@example.com".
  string destination = 2; // email

  // Operations on locked aliases require a priviliged API key.
  bool locked = 3;

  // If "can_send" is true, it is possible to send emails with
  // the "source" address in the sender field.
  bool can_send = 4;

  // A human readable comment about this alias. Can be empty.
  string comment = 5;

  // User, who created the alias. May be empty if user cannot be determined.
  string created_by = 6;

  // Unix-timestamp (seconds) of the time of creation of the alias
  int64 created_at = 7;
}

message ListAliasesRequest {
  // email, optional
  // If supplied, only aliases with that "source" are returned.
  string source = 1;

  // email, optional
  // If supplied, only aliases with that "destination" are returned.
  string destination = 2;
}

message CreateAliasRequest {
  string source = 1; // email, required
  string destination = 2; // email, required
  bool locked = 3;
  bool can_send = 4;
  string comment = 5; // optional
}

message DeleteAliasRequest {
  string source = 1; // email, required
  string destination = 2; // email, required
}

message UserLoginRequest {
  string username = 1; // required
  string password = 2; // required
}

message UserLoginResponse {
  // If the credentials are wrong, a PermissionDenied (7) error is returned.
  string session_token = 1;
}

message LoginValidationRequest {
  string session_token = 1; // required
}

message SystemStatusResponse {
  message Server {
    string name = 2;
    SyncStatus status = 1;
  }

  enum SyncStatus {
    UNKNOWN = 0; // The API has no connection to this server. It is unknown which aliases it has.
    UP_TO_DATE = 1; // The server is connected and has up to date aliases.
    OUTDATED = 2; // The server is connected, but doesn't have up to date aliases. This is typically transient.
  }

  repeated Server mail_servers = 1;
  bool shadowed_exist = 2; // Some aliases are shadowed by others. Administrators should have already been notified.
}