Class: Mailtrap::EmailCampaignsAPI

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

Instance Attribute Summary collapse

Attributes included from BaseAPI

#account_id

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



28
29
30
 
# File 'lib/mailtrap/email_campaigns_api.rb', line 28

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

Instance Attribute Details

#client ⇒ Object (readonly)

Returns the value of attribute client.



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

def 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:



137
138
139
 
# File 'lib/mailtrap/email_campaigns_api.rb', line 137

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:



78
79
80
 
# File 'lib/mailtrap/email_campaigns_api.rb', line 78

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:



110
111
112
 
# File 'lib/mailtrap/email_campaigns_api.rb', line 110

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:



56
57
58
 
# File 'lib/mailtrap/email_campaigns_api.rb', line 56

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:



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

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:



154
155
156
 
# File 'lib/mailtrap/email_campaigns_api.rb', line 154

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:



129
130
131
 
# File 'lib/mailtrap/email_campaigns_api.rb', line 129

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:



118
119
120
 
# File 'lib/mailtrap/email_campaigns_api.rb', line 118

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:



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

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:



146
147
148
 
# File 'lib/mailtrap/email_campaigns_api.rb', line 146

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:



102
103
104
 
# File 'lib/mailtrap/email_campaigns_api.rb', line 102

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