Class: Mailtrap::EmailCampaignsAPI

Inherits:
Object
  • Object
show all
Includes:
BaseAPI
Defined in:
lib/mailtrap/email_campaigns_api.rb

Instance Attribute Summary

Attributes included from BaseAPI

#account_id, #client

Instance Method Summary collapse

Methods included from BaseAPI

included

Constructor Details

#initialize(client = Mailtrap::Client.new) ⇒ EmailCampaignsAPI

Returns a new instance of EmailCampaignsAPI.

Parameters:

  • client (Mailtrap::Client) (defaults to: Mailtrap::Client.new) —

    The client instance



26
27
28
 
# File 'lib/mailtrap/email_campaigns_api.rb', line 26

def initialize(client = Mailtrap::Client.new)
  @client = client
end

Instance Method Details

#cancel(email_campaign_id) ⇒ EmailCampaign

Cancels a scheduled campaign, returning it to the draft state

Parameters:

  • email_campaign_id (Integer) —

    The email campaign ID

Returns:

Raises:



135
136
137
 
# File 'lib/mailtrap/email_campaigns_api.rb', line 135

def cancel(email_campaign_id)
  perform_action(email_campaign_id, :cancel)
end

#create(options) ⇒ EmailCampaign

Creates a new email campaign in the draft state

Parameters:

  • options (Hash) —

    The parameters to create

Options Hash (options):

  • :name (String) —

    Campaign name (required)

  • :domain_id (Integer) —

    ID of the verified sending domain (required), as returned by the Sending Domains endpoints

  • :from_display_name (String) —

    Display name shown in the From header

  • :from_local_part (String) —

    Local part (before the @) of the From address (required)

  • :reply_to (Hash) —

    Reply-To address parts (+display_name+, local_part, domain)

  • :template_attributes (Hash) —

    Template attributes (+subject+ (required), body_html, body_text, merge_tags)

  • :delivery_mode (String) —

    How the campaign is delivered (+rapid+ or gradual)

  • :delivery_options (Hash) —

    Delivery throttling options (+emails_per_hour+), applies when delivery_mode is gradual

  • :contact_list_ids (Array<Integer>) —

    IDs of contact lists to send to

  • :contact_segment_ids (Array<Integer>) —

    IDs of contact segments to send to

Returns:

Raises:



76
77
78
 
# File 'lib/mailtrap/email_campaigns_api.rb', line 76

def create(options)
  base_create(options)
end

#delete(email_campaign_id) ⇒ nil

Deletes an email campaign. Only a campaign in the draft state can be deleted.

Parameters:

  • email_campaign_id (Integer) —

    The email campaign ID

Returns:

  • (nil)

Raises:



108
109
110
 
# File 'lib/mailtrap/email_campaigns_api.rb', line 108

def delete(email_campaign_id)
  base_delete(email_campaign_id)
end

#get(email_campaign_id) ⇒ EmailCampaign

Retrieves a specific email campaign

Parameters:

  • email_campaign_id (Integer) —

    The email campaign ID

Returns:

Raises:



54
55
56
 
# File 'lib/mailtrap/email_campaigns_api.rb', line 54

def get(email_campaign_id)
  base_get(email_campaign_id)
end

#list(per_page: nil, search: nil, token: nil) ⇒ EmailCampaignsListResponse

Lists email campaigns for the account, newest first

Parameters:

  • per_page (Integer, nil) (defaults to: nil) —

    Number of campaigns per page (max 100, default 50)

  • search (String, nil) (defaults to: nil) —

    Filter campaigns by name

  • token (Integer, nil) (defaults to: nil) —

    Page number to retrieve (page-token pagination, default 1)

Returns:

Raises:



36
37
38
39
40
41
42
43
44
45
46
47
48
 
# File 'lib/mailtrap/email_campaigns_api.rb', line 36

def list(per_page: nil, search: nil, token: nil)
  query_params = {}
  query_params[:per_page] = per_page unless per_page.nil?
  query_params[:search] = search unless search.nil?
  query_params[:token] = token unless token.nil?

  response = client.get(base_path, query_params)

  EmailCampaignsListResponse.new(
    data: Array(response[:data]).map { |item| build_entity(item, response_class) },
    pagination: response[:pagination]
  )
end

#reset(email_campaign_id) ⇒ EmailCampaign

Resets a scheduled campaign back to the draft state

Parameters:

  • email_campaign_id (Integer) —

    The email campaign ID

Returns:

Raises:



152
153
154
 
# File 'lib/mailtrap/email_campaigns_api.rb', line 152

def reset(email_campaign_id)
  perform_action(email_campaign_id, :reset)
end

#schedule(email_campaign_id, datetime) ⇒ EmailCampaign

Schedules a draft campaign to start sending at a future time. The time is reported back in current_state_metadata.scheduled_at.

Parameters:

  • email_campaign_id (Integer) —

    The email campaign ID

  • datetime (String) —

    When to send the campaign (ISO 8601); must be in the future and no more than 1 month ahead

Returns:

Raises:



127
128
129
 
# File 'lib/mailtrap/email_campaigns_api.rb', line 127

def schedule(email_campaign_id, datetime)
  perform_action(email_campaign_id, :schedule, { datetime: })
end

#start(email_campaign_id) ⇒ EmailCampaign

Starts sending a draft campaign immediately

Parameters:

  • email_campaign_id (Integer) —

    The email campaign ID

Returns:

Raises:



116
117
118
 
# File 'lib/mailtrap/email_campaigns_api.rb', line 116

def start(email_campaign_id)
  perform_action(email_campaign_id, :start)
end

#stats(email_campaign_id, start_date: nil, end_date: nil) ⇒ EmailCampaignStats

Retrieves aggregated performance statistics for an email campaign. By default statistics are aggregated since the campaign was last started.

Parameters:

  • email_campaign_id (Integer) —

    The email campaign ID

  • start_date (String, nil) (defaults to: nil) —

    Start of the aggregation window (inclusive), YYYY-MM-DD

  • end_date (String, nil) (defaults to: nil) —

    End of the aggregation window (inclusive), YYYY-MM-DD

Returns:

Raises:



163
164
165
166
167
168
169
170
 
# File 'lib/mailtrap/email_campaigns_api.rb', line 163

def stats(email_campaign_id, start_date: nil, end_date: nil)
  query_params = {}
  query_params[:start_date] = start_date unless start_date.nil?
  query_params[:end_date] = end_date unless end_date.nil?

  response = client.get("#{base_path}/#{email_campaign_id}/stats", query_params)
  build_entity(response[:data], EmailCampaignStats)
end

#terminate(email_campaign_id) ⇒ EmailCampaign

Terminates a campaign that is currently sending (+started+, queued, or paused), aborting the in-flight send

Parameters:

  • email_campaign_id (Integer) —

    The email campaign ID

Returns:

Raises:



144
145
146
 
# File 'lib/mailtrap/email_campaigns_api.rb', line 144

def terminate(email_campaign_id)
  perform_action(email_campaign_id, :terminate)
end

#update(email_campaign_id, options) ⇒ EmailCampaign

Updates an existing draft email campaign. Only the provided attributes are changed; template_attributes sub-fields are also updated partially, in place.

Parameters:

  • email_campaign_id (Integer) —

    The email campaign ID

  • options (Hash) —

    The parameters to update; accepts the same fields as #create

Options Hash (options):

  • :name (String) —

    Campaign name

  • :domain_id (Integer) —

    ID of the verified sending domain, as returned by the Sending Domains endpoints

  • :from_display_name (String) —

    Display name shown in the From header

  • :from_local_part (String) —

    Local part (before the @) of the From address

  • :reply_to (Hash) —

    Reply-To address parts (+display_name+, local_part, domain)

  • :template_attributes (Hash) —

    Template attributes (+subject+, body_html, body_text, merge_tags)

  • :delivery_mode (String) —

    How the campaign is delivered (+rapid+ or gradual)

  • :delivery_options (Hash) —

    Delivery throttling options (+emails_per_hour+), applies when delivery_mode is gradual

  • :contact_list_ids (Array<Integer>) —

    IDs of contact lists to send to

  • :contact_segment_ids (Array<Integer>) —

    IDs of contact segments to send to

Returns:

Raises:



100
101
102
 
# File 'lib/mailtrap/email_campaigns_api.rb', line 100

def update(email_campaign_id, options)
  base_update(email_campaign_id, options)
end