Yugo

https://hexdocs.pm/yugo/
Admin
Yugo is an easy and high-level IMAP client library for Elixir.
Tokens:2,505
Snippets:40
Trust Score:9
Update:3 months ago
Show doc for...
Tokens:
Raw
### Starting an IMAP client process

Source: https://hexdocs.pm/yugo/Yugo.Client.html

Starts a linked IMAP client process using the specified configuration arguments.

```elixir
@spec start_link(
  server: String.t(),
  username: String.t(),
  password: String.t(),
  name: name(),
  port: 1..65535,
  tls: boolean(),
  ssl_verify: :verify_none | :verify_peer,
  mailbox: String.t()
) :: GenServer.on_start()
```

--------------------------------

### start_link(args)

Source: https://hexdocs.pm/yugo/Yugo.Client.html

Starts an IMAP client process linked to the calling process. This is typically invoked by a supervisor.

```APIDOC
## start_link(args)

### Description
Starts an IMAP client process linked to the calling process. This function is typically used within a supervision tree.

### Parameters
- **server** (String.t) - Required - The location of the IMAP server (e.g., "imap.example.com").
- **username** (String.t) - Required - Username used to log in.
- **password** (String.t) - Required - Password used to log in.
- **name** (name()) - Required - A name used to reference this Client.
- **port** (1..65535) - Optional - The port to connect to the server via. Defaults to 993.
- **tls** (boolean) - Optional - Whether or not to connect using TLS. Defaults to true.
- **ssl_verify** (:verify_none | :verify_peer) - Optional - The :verify option passed to :ssl.connect/2. Defaults to :verify_peer.
- **mailbox** (String.t) - Optional - The name of the mailbox to monitor for emails. Defaults to "INBOX".
```

--------------------------------

### child_spec(init_arg)

Source: https://hexdocs.pm/yugo/Yugo.Client.html

Returns a specification to start this module under a supervisor.

```APIDOC
## child_spec(init_arg)

### Description
Returns a specification to start this module under a supervisor.
```

--------------------------------

### Initialize a filter

Source: https://hexdocs.pm/yugo/Yugo.Filter.html

Returns a filter that accepts all emails.

```elixir
@spec all() :: t()
```

--------------------------------

### Supervise Yugo.Client in Application

Source: https://hexdocs.pm/yugo/readme.html

Add Yugo.Client to the application supervision tree to manage the IMAP connection lifecycle.

```elixir
defmodule MyApp.Application do
  use Application

  @impl true
  def start(_type, _args) do
    children = [
      {Yugo.Client,
       name: :example_client,
       server: "imap.example.com",
       username: "me@example.com",
       password: "pa55w0rd"}
    ]

    Supervisor.start_link(children, strategy: :one_for_one)
  end
end
```

--------------------------------

### Subscribe to a client

Source: https://hexdocs.pm/yugo/Yugo.html

Subscribes the calling process to a client, optionally using a filter.

```elixir
@spec subscribe(Yugo.Client.name(), Yugo.Filter.t()) :: :ok
```

--------------------------------

### Define mime_type type

Source: https://hexdocs.pm/yugo/Yugo.html

Represents a MIME type as a string.

```elixir
@type mime_type() :: String.t()
```

--------------------------------

### Define flag type

Source: https://hexdocs.pm/yugo/Yugo.html

Enumeration of possible email flags.

```elixir
@type flag() :: :seen | :answered | :flagged | :draft | :deleted
```

--------------------------------

### Defining the name type

Source: https://hexdocs.pm/yugo/Yugo.Client.html

The identifier used to refer to a Client process.

```elixir
@type name() :: term()
```

--------------------------------

### subscribe(client_name, filter)

Source: https://hexdocs.pm/yugo/Yugo.html

Subscribes the calling process to the specified email client. Notifications are received as messages in the format {:email, client, message}.

```APIDOC
## subscribe(client_name, filter)

### Description
Subscribes the calling process to the `Client` named by `client_name`. When subscribed, the process receives notifications for new emails.

### Signature
`subscribe(client_name, filter \\ Filter.all()) :: :ok`

### Parameters
- **client_name** (Yugo.Client.name()) - Required - The name of the client to subscribe to.
- **filter** (Yugo.Filter.t()) - Optional - A filter to match specific emails. Defaults to `Filter.all()`.
```

--------------------------------

### Create a complex email filter

Source: https://hexdocs.pm/yugo/Yugo.Filter.html

Combines multiple filter criteria to match specific read, unreplied emails with a matching subject.

```elixir
alias Yugo.Filter

my_filter =
  Filter.all()
  |> Filter.has_flag(:seen)
  |> Filter.lacks_flag(:answered)
  |> Filter.subject_matches(~r/Order Information/)
```

--------------------------------

### Subscribe to Filtered Emails

Source: https://hexdocs.pm/yugo/readme.html

Define a filter and subscribe to email notifications using the client name and filter criteria.

```elixir
# filter to only notify us about messages containing "hello" or "goodbye" in the subject:
my_filter =
  Yugo.Filter.all()
  |> Yugo.Filter.subject_matches(~r/(hello|goodbye)/)

# By subscribing, our process will be notified about all future emails that match the filter.
Yugo.subscribe(:example_client, my_filter)

receive do
  {:email, _client, message} ->
    IO.puts("Received an email with subject `#{message.subject}`:")
    IO.inspect(message)
end
```

--------------------------------

### Filter by sender

Source: https://hexdocs.pm/yugo/Yugo.Filter.html

Accepts emails where the sender address matches a regex.

```elixir
@spec sender_matches(t(), Regex.t()) :: t()
```

```elixir
alias Yugo.Filter

# make a filter that only accepts emails sent from "peter@example.com" or "alex@example.com"
Filter.all()
|> Filter.sender_matches(~r/^(peter|alex)@example.com$/i)
```

--------------------------------

### Filter by subject

Source: https://hexdocs.pm/yugo/Yugo.Filter.html

Accepts emails where the subject line matches a regex.

```elixir
@spec subject_matches(t(), Regex.t()) :: t()
```

--------------------------------

### Define body type

Source: https://hexdocs.pm/yugo/Yugo.html

Represents an email body as either a single part or a multipart structure.

```elixir
@type body() ::
  {mime_type(), %{optional(String.t()) => String.t()}, binary()} | [body()]
```

--------------------------------

### Unsubscribe from a client

Source: https://hexdocs.pm/yugo/Yugo.html

Removes the calling process from all notifications for the specified client.

```elixir
@spec unsubscribe(Yugo.Client.name()) :: :ok
```

--------------------------------

### Define address type

Source: https://hexdocs.pm/yugo/Yugo.html

Represents an email address with an optional associated name.

```elixir
@type address() :: {nil | String.t(), String.t()}
```

--------------------------------

### Yugo.Filter API

Source: https://hexdocs.pm/yugo/Yugo.Filter.html

The Yugo.Filter module provides functions to construct filters for email notifications. These functions are designed to be chained using the pipe operator.

```APIDOC
## all()
Returns a `Filter` that accepts all emails.

## has_flag(filter, flag)
Only accepts emails that have the specified flag. Flags include `:seen`, `:answered`, `:flagged`, `:draft`, and `:deleted`.

## lacks_flag(filter, flag)
Only accepts emails that do not have the specified flag.

## sender_matches(filter, pattern)
Accepts emails where the email address of the sender matches the given `Regex`.

## subject_matches(filter, pattern)
Accepts emails whose "subject" line matches the given `Regex`.
```

--------------------------------

### Define email type

Source: https://hexdocs.pm/yugo/Yugo.html

Structure of an email message sent to a subscribed process.

```elixir
@type email() :: %{
  bcc: [address()],
  body: body(),
  cc: [address()],
  date: DateTime.t(),
  flags: [flag()],
  in_reply_to: nil | String.t(),
  message_id: nil | String.t(),
  reply_to: [address()],
  sender: [address()],
  from: [address()],
  subject: nil | String.t(),
  to: [address()]
}
```

--------------------------------

### Filter by flag presence

Source: https://hexdocs.pm/yugo/Yugo.Filter.html

Accepts emails that have a specific flag set.

```elixir
@spec has_flag(t(), Yugo.flag()) :: t()
```

```elixir
alias Filter

# build a filter that only allows messages that have been seen.
Filter.all()
|> Filter.has_flag(:seen)
```

--------------------------------

### unsubscribe(client_name)

Source: https://hexdocs.pm/yugo/Yugo.html

Unsubscribes the calling process from the specified email client.

```APIDOC
## unsubscribe(client_name)

### Description
Unsubscribes the calling process from the specified `Client`. This removes all subscriptions for the calling process from the given client.

### Signature
`unsubscribe(client_name) :: :ok`

### Parameters
- **client_name** (Yugo.Client.name()) - Required - The name of the client to unsubscribe from.
```

--------------------------------

### Filter by flag absence

Source: https://hexdocs.pm/yugo/Yugo.Filter.html

Accepts emails that do not have a specific flag set.

```elixir
@spec lacks_flag(t(), Yugo.flag()) :: t()
```

```elixir
alias Filter

# build a filter that allows all messages that do not have the :deleted flag
Filter.all()
|> Filter.lacks_flag(:deleted)
```

--------------------------------

### Define the Filter type

Source: https://hexdocs.pm/yugo/Yugo.Filter.html

The internal structure of the Filter struct.

```elixir
@type t() :: %Yugo.Filter{
  has_flags: [Yugo.flag()],
  lacks_flags: [Yugo.flag()],
  sender_regex: nil | Regex.t(),
  subject_regex: nil | Regex.t()
}
```
Tokens:
Raw