# File Mandrill/Senders.php

      1: <?php
      2:
      3: class Mandrill_Senders {
      4:     public function __construct(Mandrill $master) {
      5:         $this->master = $master;
      6:     }
      7:
      8:     /**
      9:      * Return the senders that have tried to use this account.
     10:      * @return array an array of sender data, one for each sending addresses used by the account
     11:      *     - return[] struct the information on each sending address in the account
     12:      *         - address string the sender's email address
     13:      *         - created_at string the date and time that the sender was first seen by Mandrill as a UTC date string in YYYY-MM-DD HH:MM:SS format
     14:      *         - sent integer the total number of messages sent by this sender
     15:      *         - hard_bounces integer the total number of hard bounces by messages by this sender
     16:      *         - soft_bounces integer the total number of soft bounces by messages by this sender
     17:      *         - rejects integer the total number of rejected messages by this sender
     18:      *         - complaints integer the total number of spam complaints received for messages by this sender
     19:      *         - unsubs integer the total number of unsubscribe requests received for messages by this sender
     20:      *         - opens integer the total number of times messages by this sender have been opened
     21:      *         - clicks integer the total number of times tracked URLs in messages by this sender have been clicked
     22:      *         - unique_opens integer the number of unique opens for emails sent for this sender
     23:      *         - unique_clicks integer the number of unique clicks for emails sent for this sender
     24:      */
     25:     public function getList() {
     26:         $_params = array();
     27:         return $this->master->call('senders/list', $_params);
     28:     }
     29:
     30:     /**
     31:      * Returns the sender domains that have been added to this account.
     32:      * @return array an array of sender domain data, one for each sending domain used by the account
     33:      *     - return[] struct the information on each sending domain for the account
     34:      *         - domain string the sender domain name
     35:      *         - created_at string the date and time that the sending domain was first seen as a UTC string in YYYY-MM-DD HH:MM:SS format
     36:      *         - last_tested_at string when the domain's DNS settings were last tested as a UTC string in YYYY-MM-DD HH:MM:SS format
     37:      *         - spf struct details about the domain's SPF record
     38:      *             - valid boolean whether the domain's SPF record is valid for use with Mandrill
     39:      *             - valid_after string when the domain's SPF record will be considered valid for use with Mandrill as a UTC string in YYYY-MM-DD HH:MM:SS format. If set, this indicates that the record is valid now, but was previously invalid, and Mandrill will wait until the record's TTL elapses to start using it.
     40:      *             - error string an error describing the spf record, or null if the record is correct
     41:      *         - dkim struct details about the domain's DKIM record
     42:      *             - valid boolean whether the domain's DKIM record is valid for use with Mandrill
     43:      *             - valid_after string when the domain's DKIM record will be considered valid for use with Mandrill as a UTC string in YYYY-MM-DD HH:MM:SS format. If set, this indicates that the record is valid now, but was previously invalid, and Mandrill will wait until the record's TTL elapses to start using it.
     44:      *             - error string an error describing the DKIM record, or null if the record is correct
     45:      *         - verified_at string if the domain has been verified, this indicates when that verification occurred as a UTC string in YYYY-MM-DD HH:MM:SS format
     46:      *         - valid_signing boolean whether this domain can be used to authenticate mail, either for itself or as a custom signing domain. If this is false but spf and dkim are both valid, you will need to verify the domain before using it to authenticate mail
     47:      */
     48:     public function domains() {
     49:         $_params = array();
     50:         return $this->master->call('senders/domains', $_params);
     51:     }
     52:
     53:     /**
     54:      * Adds a sender domain to your account. Sender domains are added automatically as you
     55: send, but you can use this call to add them ahead of time.
     56:      * @param string $domain a domain name
     57:      * @return struct information about the domain
     58:      *     - domain string the sender domain name
     59:      *     - created_at string the date and time that the sending domain was first seen as a UTC string in YYYY-MM-DD HH:MM:SS format
     60:      *     - last_tested_at string when the domain's DNS settings were last tested as a UTC string in YYYY-MM-DD HH:MM:SS format
     61:      *     - spf struct details about the domain's SPF record
     62:      *         - valid boolean whether the domain's SPF record is valid for use with Mandrill
     63:      *         - valid_after string when the domain's SPF record will be considered valid for use with Mandrill as a UTC string in YYYY-MM-DD HH:MM:SS format. If set, this indicates that the record is valid now, but was previously invalid, and Mandrill will wait until the record's TTL elapses to start using it.
     64:      *         - error string an error describing the spf record, or null if the record is correct
     65:      *     - dkim struct details about the domain's DKIM record
     66:      *         - valid boolean whether the domain's DKIM record is valid for use with Mandrill
     67:      *         - valid_after string when the domain's DKIM record will be considered valid for use with Mandrill as a UTC string in YYYY-MM-DD HH:MM:SS format. If set, this indicates that the record is valid now, but was previously invalid, and Mandrill will wait until the record's TTL elapses to start using it.
     68:      *         - error string an error describing the DKIM record, or null if the record is correct
     69:      *     - verified_at string if the domain has been verified, this indicates when that verification occurred as a UTC string in YYYY-MM-DD HH:MM:SS format
     70:      *     - valid_signing boolean whether this domain can be used to authenticate mail, either for itself or as a custom signing domain. If this is false but spf and dkim are both valid, you will need to verify the domain before using it to authenticate mail
     71:      */
     72:     public function addDomain($domain) {
     73:         $_params = array("domain" => $domain);
     74:         return $this->master->call('senders/add-domain', $_params);
     75:     }
     76:
     77:     /**
     78:      * Checks the SPF and DKIM settings for a domain. If you haven't already added this domain to your
     79: account, it will be added automatically.
     80:      * @param string $domain a domain name
     81:      * @return struct information about the sender domain
     82:      *     - domain string the sender domain name
     83:      *     - created_at string the date and time that the sending domain was first seen as a UTC string in YYYY-MM-DD HH:MM:SS format
     84:      *     - last_tested_at string when the domain's DNS settings were last tested as a UTC string in YYYY-MM-DD HH:MM:SS format
     85:      *     - spf struct details about the domain's SPF record
     86:      *         - valid boolean whether the domain's SPF record is valid for use with Mandrill
     87:      *         - valid_after string when the domain's SPF record will be considered valid for use with Mandrill as a UTC string in YYYY-MM-DD HH:MM:SS format. If set, this indicates that the record is valid now, but was previously invalid, and Mandrill will wait until the record's TTL elapses to start using it.
     88:      *         - error string an error describing the spf record, or null if the record is correct
     89:      *     - dkim struct details about the domain's DKIM record
     90:      *         - valid boolean whether the domain's DKIM record is valid for use with Mandrill
     91:      *         - valid_after string when the domain's DKIM record will be considered valid for use with Mandrill as a UTC string in YYYY-MM-DD HH:MM:SS format. If set, this indicates that the record is valid now, but was previously invalid, and Mandrill will wait until the record's TTL elapses to start using it.
     92:      *         - error string an error describing the DKIM record, or null if the record is correct
     93:      *     - verified_at string if the domain has been verified, this indicates when that verification occurred as a UTC string in YYYY-MM-DD HH:MM:SS format
     94:      *     - valid_signing boolean whether this domain can be used to authenticate mail, either for itself or as a custom signing domain. If this is false but spf and dkim are both valid, you will need to verify the domain before using it to authenticate mail
     95:      */
     96:     public function checkDomain($domain) {
     97:         $_params = array("domain" => $domain);
     98:         return $this->master->call('senders/check-domain', $_params);
     99:     }
    100:
    101:     /**
    102:      * Sends a verification email in order to verify ownership of a domain.
    103: Domain verification is an optional step to confirm ownership of a domain. Once a
    104: domain has been verified in a Mandrill account, other accounts may not have their
    105: messages signed by that domain unless they also verify the domain. This prevents
    106: other Mandrill accounts from sending mail signed by your domain.
    107:      * @param string $domain a domain name at which you can receive email
    108:      * @param string $mailbox a mailbox at the domain where the verification email should be sent
    109:      * @return struct information about the verification that was sent
    110:      *     - status string "sent" indicates that the verification has been sent, "already_verified" indicates that the domain has already been verified with your account
    111:      *     - domain string the domain name you provided
    112:      *     - email string the email address the verification email was sent to
    113:      */
    114:     public function verifyDomain($domain, $mailbox) {
    115:         $_params = array("domain" => $domain, "mailbox" => $mailbox);
    116:         return $this->master->call('senders/verify-domain', $_params);
    117:     }
    118:
    119:     /**
    120:      * Return more detailed information about a single sender, including aggregates of recent stats
    121:      * @param string $address the email address of the sender
    122:      * @return struct the detailed information on the sender
    123:      *     - address string the sender's email address
    124:      *     - created_at string the date and time that the sender was first seen by Mandrill as a UTC date string in YYYY-MM-DD HH:MM:SS format
    125:      *     - sent integer the total number of messages sent by this sender
    126:      *     - hard_bounces integer the total number of hard bounces by messages by this sender
    127:      *     - soft_bounces integer the total number of soft bounces by messages by this sender
    128:      *     - rejects integer the total number of rejected messages by this sender
    129:      *     - complaints integer the total number of spam complaints received for messages by this sender
    130:      *     - unsubs integer the total number of unsubscribe requests received for messages by this sender
    131:      *     - opens integer the total number of times messages by this sender have been opened
    132:      *     - clicks integer the total number of times tracked URLs in messages by this sender have been clicked
    133:      *     - stats struct an aggregate summary of the sender's sending stats
    134:      *         - today struct stats for this sender so far today
    135:      *             - sent integer the number of emails sent for this sender so far today
    136:      *             - hard_bounces integer the number of emails hard bounced for this sender so far today
    137:      *             - soft_bounces integer the number of emails soft bounced for this sender so far today
    138:      *             - rejects integer the number of emails rejected for sending this sender so far today
    139:      *             - complaints integer the number of spam complaints for this sender so far today
    140:      *             - unsubs integer the number of unsubscribes for this sender so far today
    141:      *             - opens integer the number of times emails have been opened for this sender so far today
    142:      *             - unique_opens integer the number of unique opens for emails sent for this sender so far today
    143:      *             - clicks integer the number of URLs that have been clicked for this sender so far today
    144:      *             - unique_clicks integer the number of unique clicks for emails sent for this sender so far today
    145:      *         - last_7_days struct stats for this sender in the last 7 days
    146:      *             - sent integer the number of emails sent for this sender in the last 7 days
    147:      *             - hard_bounces integer the number of emails hard bounced for this sender in the last 7 days
    148:      *             - soft_bounces integer the number of emails soft bounced for this sender in the last 7 days
    149:      *             - rejects integer the number of emails rejected for sending this sender in the last 7 days
    150:      *             - complaints integer the number of spam complaints for this sender in the last 7 days
    151:      *             - unsubs integer the number of unsubscribes for this sender in the last 7 days
    152:      *             - opens integer the number of times emails have been opened for this sender in the last 7 days
    153:      *             - unique_opens integer the number of unique opens for emails sent for this sender in the last 7 days
    154:      *             - clicks integer the number of URLs that have been clicked for this sender in the last 7 days
    155:      *             - unique_clicks integer the number of unique clicks for emails sent for this sender in the last 7 days
    156:      *         - last_30_days struct stats for this sender in the last 30 days
    157:      *             - sent integer the number of emails sent for this sender in the last 30 days
    158:      *             - hard_bounces integer the number of emails hard bounced for this sender in the last 30 days
    159:      *             - soft_bounces integer the number of emails soft bounced for this sender in the last 30 days
    160:      *             - rejects integer the number of emails rejected for sending this sender in the last 30 days
    161:      *             - complaints integer the number of spam complaints for this sender in the last 30 days
    162:      *             - unsubs integer the number of unsubscribes for this sender in the last 30 days
    163:      *             - opens integer the number of times emails have been opened for this sender in the last 30 days
    164:      *             - unique_opens integer the number of unique opens for emails sent for this sender in the last 30 days
    165:      *             - clicks integer the number of URLs that have been clicked for this sender in the last 30 days
    166:      *             - unique_clicks integer the number of unique clicks for emails sent for this sender in the last 30 days
    167:      *         - last_60_days struct stats for this sender in the last 60 days
    168:      *             - sent integer the number of emails sent for this sender in the last 60 days
    169:      *             - hard_bounces integer the number of emails hard bounced for this sender in the last 60 days
    170:      *             - soft_bounces integer the number of emails soft bounced for this sender in the last 60 days
    171:      *             - rejects integer the number of emails rejected for sending this sender in the last 60 days
    172:      *             - complaints integer the number of spam complaints for this sender in the last 60 days
    173:      *             - unsubs integer the number of unsubscribes for this sender in the last 60 days
    174:      *             - opens integer the number of times emails have been opened for this sender in the last 60 days
    175:      *             - unique_opens integer the number of unique opens for emails sent for this sender in the last 60 days
    176:      *             - clicks integer the number of URLs that have been clicked for this sender in the last 60 days
    177:      *             - unique_clicks integer the number of unique clicks for emails sent for this sender in the last 60 days
    178:      *         - last_90_days struct stats for this sender in the last 90 days
    179:      *             - sent integer the number of emails sent for this sender in the last 90 days
    180:      *             - hard_bounces integer the number of emails hard bounced for this sender in the last 90 days
    181:      *             - soft_bounces integer the number of emails soft bounced for this sender in the last 90 days
    182:      *             - rejects integer the number of emails rejected for sending this sender in the last 90 days
    183:      *             - complaints integer the number of spam complaints for this sender in the last 90 days
    184:      *             - unsubs integer the number of unsubscribes for this sender in the last 90 days
    185:      *             - opens integer the number of times emails have been opened for this sender in the last 90 days
    186:      *             - unique_opens integer the number of unique opens for emails sent for this sender in the last 90 days
    187:      *             - clicks integer the number of URLs that have been clicked for this sender in the last 90 days
    188:      *             - unique_clicks integer the number of unique clicks for emails sent for this sender in the last 90 days
    189:      */
    190:     public function info($address) {
    191:         $_params = array("address" => $address);
    192:         return $this->master->call('senders/info', $_params);
    193:     }
    194:
    195:     /**
    196:      * Return the recent history (hourly stats for the last 30 days) for a sender
    197:      * @param string $address the email address of the sender
    198:      * @return array the array of history information
    199:      *     - return[] struct the stats for a single hour
    200:      *         - time string the hour as a UTC date string in YYYY-MM-DD HH:MM:SS format
    201:      *         - sent integer the number of emails that were sent during the hour
    202:      *         - hard_bounces integer the number of emails that hard bounced during the hour
    203:      *         - soft_bounces integer the number of emails that soft bounced during the hour
    204:      *         - rejects integer the number of emails that were rejected during the hour
    205:      *         - complaints integer the number of spam complaints received during the hour
    206:      *         - opens integer the number of emails opened during the hour
    207:      *         - unique_opens integer the number of unique opens generated by messages sent during the hour
    208:      *         - clicks integer the number of tracked URLs clicked during the hour
    209:      *         - unique_clicks integer the number of unique clicks generated by messages sent during the hour
    210:      */
    211:     public function timeSeries($address) {
    212:         $_params = array("address" => $address);
    213:         return $this->master->call('senders/time-series', $_params);
    214:     }
    215:
    216: }
    217:
    218:
    219: